@cursor/bdk 0.2.1

package/dist/internal/filesystem/errors.js

@@ -0,0 +1,172 @@
+/**
+ * Typed FileSystem throws. Every method error is a {@link PathError}
+ * so composers (`unionFs`) can rewrite `path` without scraping
+ * `error.message`.
+ *
+ * Messages stay the FileSystem contract strings. `path` is the
+ * absolute posix path the error is about (child-root on a mount,
+ * namespace path after `unionFs` remaps it).
+ */
+import path from "node:path";
+function normalizeErrorPath(input) {
+    const slashes = input.replace(/\\/g, "/");
+    if (slashes === "") {
+        return "/";
+    }
+    const withSlash = slashes.startsWith("/") ? slashes : `/${slashes}`;
+    const resolved = path.posix.normalize(withSlash);
+    if (resolved.length > 1 && resolved.endsWith("/")) {
+        return resolved.slice(0, -1);
+    }
+    return resolved === "." || resolved === "" ? "/" : resolved;
+}
+const ROOT_MESSAGE_PREFIX = /^(not found|read-only mount|write failed|edit failed|no mount for path|delete is not supported): \/$/;
+function rewritePathInMessage(message, from, to) {
+    if (from === to) {
+        return message;
+    }
+    if (from === "/") {
+        return ROOT_MESSAGE_PREFIX.test(message) ? message.replace(/\/$/, to) : message;
+    }
+    return message.includes(from) ? message.split(from).join(to) : message;
+}
+/**
+ * Base of every FileSystem method throw. Config / factory errors
+ * (`FileSystemConfigError`, empty `overlayFs`) are not PathErrors.
+ */
+export class PathError extends Error {
+    constructor(path, message) {
+        super(message);
+        this.name = new.target.name;
+        this.path = normalizeErrorPath(path);
+    }
+    /**
+     * Same error at a rewritten path. `unionFs` prepends the mount
+     * prefix this way. Subclass identity and extra fields stay.
+     */
+    withPath(path) {
+        const next = normalizeErrorPath(path);
+        if (next === this.path) {
+            return this;
+        }
+        return this.recreate(next, rewritePathInMessage(this.message, this.path, next));
+    }
+    recreate(path, message) {
+        return new PathError(path, message);
+    }
+}
+export class FileNotFoundError extends PathError {
+    constructor(path, message) {
+        super(path, message !== null && message !== void 0 ? message : `not found: ${normalizeErrorPath(path)}`);
+    }
+    recreate(path, message) {
+        return new FileNotFoundError(path, message);
+    }
+}
+export class ReadOnlyMountError extends PathError {
+    constructor(path, message) {
+        super(path, message !== null && message !== void 0 ? message : `read-only mount: ${normalizeErrorPath(path)}`);
+    }
+    recreate(path, message) {
+        return new ReadOnlyMountError(path, message);
+    }
+}
+export class NoMountError extends PathError {
+    constructor(path, message) {
+        super(path, message !== null && message !== void 0 ? message : `no mount for path: ${normalizeErrorPath(path)}`);
+    }
+    recreate(path, message) {
+        return new NoMountError(path, message);
+    }
+}
+export class WriteFailedError extends PathError {
+    constructor(path, message) {
+        super(path, message !== null && message !== void 0 ? message : `write failed: ${normalizeErrorPath(path)}`);
+    }
+    recreate(path, message) {
+        return new WriteFailedError(path, message);
+    }
+}
+export class DeleteNotSupportedError extends PathError {
+    constructor(path, message) {
+        super(path, message !== null && message !== void 0 ? message : `delete is not supported: ${normalizeErrorPath(path)}`);
+    }
+    recreate(path, message) {
+        return new DeleteNotSupportedError(path, message);
+    }
+}
+/**
+ * Exact-edit contract failures (`oldText is empty`, uniqueness).
+ * `message` is the contract string; it does not embed `path`.
+ */
+export class EditError extends PathError {
+    recreate(path, message) {
+        return new EditError(path, message);
+    }
+}
+export class InvalidGrepPatternError extends PathError {
+    constructor(pattern, path = "/", message) {
+        super(path, message !== null && message !== void 0 ? message : `invalid grep pattern: ${pattern}`);
+        this.pattern = pattern;
+    }
+    recreate(path, message) {
+        return new InvalidGrepPatternError(this.pattern, path, message);
+    }
+}
+export function isFileNotFoundError(error) {
+    return (error instanceof FileNotFoundError ||
+        (error instanceof Error && error.message.startsWith("not found:")));
+}
+export function isInvalidGrepPatternError(error) {
+    return (error instanceof InvalidGrepPatternError ||
+        (error instanceof Error && error.message.startsWith("invalid grep pattern:")));
+}
+const CONTRACT_PATH_LABELS = [
+    "not found: ",
+    "read-only mount: ",
+    "write failed: ",
+    "edit failed: ",
+    "no mount for path: ",
+    "delete is not supported: ",
+];
+/**
+ * Remap a child throw onto a mount prefix. Typed {@link PathError}
+ * keeps its class and rewrites `path`. Untyped `Error` still gets
+ * a best-effort message rewrite so older custom trees keep working.
+ */
+export function remapPathError(error, prefix) {
+    if (error instanceof PathError) {
+        return error.withPath(joinMountPath(error.path, prefix));
+    }
+    if (!(error instanceof Error)) {
+        return new PathError(prefix, String(error));
+    }
+    return rewriteUntypedMountError(error, prefix);
+}
+function joinMountPath(childPath, prefix) {
+    const mount = normalizeErrorPath(prefix);
+    const child = normalizeErrorPath(childPath);
+    if (mount === "/") {
+        return child;
+    }
+    if (child === "/") {
+        return mount;
+    }
+    return `${mount}${child}`;
+}
+function rewriteUntypedMountError(error, prefix) {
+    for (const label of CONTRACT_PATH_LABELS) {
+        if (!error.message.startsWith(label)) {
+            continue;
+        }
+        const childPath = error.message.slice(label.length);
+        const next = `${label}${joinMountPath(childPath, prefix)}`;
+        if (next === error.message) {
+            return error;
+        }
+        const rewritten = new Error(next);
+        rewritten.name = error.name;
+        return rewritten;
+    }
+    return error;
+}

package/dist/internal/filesystem/format.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Model-facing strings that match Cursor SDK native tool output
+ * (LocalLsExecutor / read / grep / glob formatters).
+ */
+import type { GrepUnionResult } from "../../filesystem.js";
+import type { LsDirectoryTreeNode } from "./walk.js";
+/**
+ * Number already-sliced Read content. `FileSystem.read` applies offset/
+ * limit; do not window again or line numbers restart at 1.
+ */
+export declare function slicedReadStartLine(totalLines: number, offset?: number): number;
+export declare function formatNumberedLines(content: string, options?: {
+    offset?: number;
+    limit?: number;
+    /** When set, `content` is already the window; number from this line. */
+    startLine?: number;
+    totalLines?: number;
+}): string;
+export declare function formatLsTree(result: LsDirectoryTreeNode): string;
+export declare function formatGlobOutput(dir: string, files: readonly string[]): string;
+export declare function formatGrepOutput(union: GrepUnionResult | undefined): string;
+export declare function formatWriteOutput(path: string): string;
+export declare function formatStrReplaceOutput(args: {
+    path: string;
+    replaceAll: boolean;
+    occurrencesModified: number;
+}): string;
+//# sourceMappingURL=format.d.ts.map

package/dist/internal/filesystem/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../../src/internal/filesystem/format.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAKrD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAQ/E;AAED,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;IACP,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;CAChB,GACL,MAAM,CAoBR;AAeD,wBAAgB,YAAY,CAAC,MAAM,EAAE,mBAAmB,GAAG,MAAM,CAsChE;AAiED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAmB9E;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,eAAe,GAAG,SAAS,GAAG,MAAM,CAwC3E;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED,wBAAgB,sBAAsB,CAAC,IAAI,EAAE;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,OAAO,CAAC;IACpB,mBAAmB,EAAE,MAAM,CAAC;CAC7B,GAAG,MAAM,CAOT"}

package/dist/internal/filesystem/format.js

@@ -0,0 +1,212 @@
+/**
+ * Model-facing strings that match Cursor SDK native tool output
+ * (LocalLsExecutor / read / grep / glob formatters).
+ */
+import { posix } from "node:path";
+const LS_RENDER_CHARACTER_BUDGET = 10000;
+const GLOB_TOTAL_CHARACTER_BUDGET = 5000;
+/**
+ * Number already-sliced Read content. `FileSystem.read` applies offset/
+ * limit; do not window again or line numbers restart at 1.
+ */
+export function slicedReadStartLine(totalLines, offset) {
+    if (offset === undefined) {
+        return 1;
+    }
+    if (offset < 0) {
+        return Math.max(1, totalLines + offset + 1);
+    }
+    return Math.max(1, offset);
+}
+export function formatNumberedLines(content, options = {}) {
+    var _a;
+    const lines = content === "" ? [] : content.split("\n");
+    if (lines.length === 0) {
+        return "";
+    }
+    const { offset, limit, startLine } = options;
+    let start = 1;
+    let window = lines;
+    const total = (_a = options.totalLines) !== null && _a !== void 0 ? _a : lines.length;
+    if (startLine !== undefined) {
+        start = startLine;
+    }
+    else if (offset !== undefined || limit !== undefined) {
+        const effectiveOffset = offset !== null && offset !== void 0 ? offset : 1;
+        const effectiveLimit = limit !== null && limit !== void 0 ? limit : (effectiveOffset < 0 ? Math.abs(effectiveOffset) : total);
+        start =
+            effectiveOffset < 0 ? Math.max(1, total + effectiveOffset + 1) : Math.max(1, effectiveOffset);
+        const end = Math.min(total, start + effectiveLimit - 1);
+        window = lines.slice(start - 1, end);
+    }
+    return renderNumberedWindow(window, start, total);
+}
+function renderNumberedWindow(window, start, total) {
+    const numbered = window.map((line, index) => `${String(start + index).padStart(6, " ")}|${line}`);
+    let result = numbered.join("\n");
+    if (start > 1) {
+        result = `... ${start - 1} ${start - 1 === 1 ? "line" : "lines"} not shown ...\n${result}`;
+    }
+    const end = start + window.length - 1;
+    if (end < total) {
+        result += `\n... ${total - end} ${total - end === 1 ? "line" : "lines"} not shown ...`;
+    }
+    return result;
+}
+export function formatLsTree(result) {
+    if (result.childrenWereProcessed &&
+        result.childrenDirs.length === 0 &&
+        result.childrenFiles.length === 0) {
+        const trailingSlash = result.absPath.endsWith("/") ? "" : "/";
+        return `${result.absPath}${trailingSlash}\n... no children found ...`;
+    }
+    const characterBudget = LS_RENDER_CHARACTER_BUDGET;
+    let toolResponse = renderDirectoryTree(result).result;
+    if (toolResponse.length > characterBudget) {
+        toolResponse = renderDirectoryTree(result, true, 0).result;
+        if (toolResponse.length > characterBudget) {
+            toolResponse = renderDirectoryTree(result, false, 0).result;
+        }
+    }
+    const notes = [];
+    if (!result.childrenWereProcessed || toolResponse.length > characterBudget) {
+        if (toolResponse.length > characterBudget) {
+            toolResponse = toolResponse.slice(0, characterBudget);
+            const lastNewlineIndex = toolResponse.lastIndexOf("\n");
+            if (lastNewlineIndex > 0) {
+                toolResponse = toolResponse.slice(0, lastNewlineIndex + 1);
+            }
+        }
+        toolResponse += "    ...\n";
+        notes.push(`target_directory is too large (either too many children or their names are too long).` +
+            ` Immediate children were truncated. Try doing more specific search or use the script tool.`);
+    }
+    if (notes.length === 1) {
+        toolResponse += `\nNote: ${notes[0]}`;
+    }
+    return toolResponse;
+}
+function renderDirectoryTree(rootDirectory, renderExtensionCounts = true, renderDepthLimit) {
+    function render(dir, depth) {
+        const indent = "  ".repeat(depth);
+        let result;
+        if (depth === 0) {
+            const trailingSep = dir.absPath.endsWith("/") ? "" : "/";
+            result = `${dir.absPath}${trailingSep}\n`;
+        }
+        else {
+            result = `${indent}- ${posix.basename(dir.absPath)}/\n`;
+        }
+        const allChildren = [
+            ...dir.childrenFiles.map((file) => ({
+                type: "file",
+                name: file.name,
+            })),
+            ...dir.childrenDirs.map((childDir) => ({
+                type: "dir",
+                name: posix.basename(childDir.absPath),
+                dir: childDir,
+            })),
+        ];
+        allChildren.sort((left, right) => left.name.localeCompare(right.name));
+        const childIndent = "  ".repeat(depth + 1);
+        for (const child of allChildren) {
+            if (child.type === "file") {
+                result += `${childIndent}- ${child.name}\n`;
+                continue;
+            }
+            const childDir = child.dir;
+            if (childDir.childrenWereProcessed &&
+                (renderDepthLimit === undefined || depth < renderDepthLimit)) {
+                result += render(childDir, depth + 1);
+                continue;
+            }
+            const extensionCounts = Object.entries(childDir.fullSubtreeExtensionCounts);
+            if (extensionCounts.length > 0 && renderExtensionCounts) {
+                const sorted = [...extensionCounts].sort(([, countA], [, countB]) => countB - countA);
+                const shown = sorted.slice(0, 3);
+                const summary = shown
+                    .map(([ext, count]) => `${count} *${ext === "" ? "" : ext}`)
+                    .join(", ");
+                result += `${childIndent}- ${child.name}/ (${childDir.numFiles} files: ${summary})\n`;
+            }
+            else {
+                result += `${childIndent}- ${child.name}/\n`;
+            }
+        }
+        return result;
+    }
+    return { result: render(rootDirectory, 0) };
+}
+export function formatGlobOutput(dir, files) {
+    var _a;
+    const normalizedRoot = dir.replace(/\/+$/, "") || "/";
+    const prefix = normalizedRoot === "/" ? "/" : `${normalizedRoot}/`;
+    const relative = files.map(filePath => filePath.startsWith(prefix) ? filePath.slice(prefix.length) : filePath);
+    if (relative.length === 0) {
+        return `Result of search in '${dir}': 0 files found\n`;
+    }
+    let output = `Result of search in '${dir}' (total ${relative.length} file${relative.length === 1 ? "" : "s"}):\n`;
+    for (let i = 0; i < relative.length; i++) {
+        const file = (_a = relative[i]) !== null && _a !== void 0 ? _a : "";
+        if (output.length + file.length > GLOB_TOTAL_CHARACTER_BUDGET) {
+            output += `... ${relative.length - i} more files ... (Do a more specific search if needed)\n`;
+            break;
+        }
+        output += `- ${file}\n`;
+    }
+    return output;
+}
+export function formatGrepOutput(union) {
+    var _a, _b, _c, _d;
+    if (union === undefined) {
+        return "No matches found";
+    }
+    if (union.type === "files") {
+        if (union.output.files.length === 0) {
+            return "No files with matches found";
+        }
+        return union.output.files.join("\n");
+    }
+    if (union.type === "count") {
+        if (union.output.counts.length === 0) {
+            return "No matches found";
+        }
+        return union.output.counts.map(row => `${row.file}:${row.count}`).join("\n");
+    }
+    if (union.output.matches.length === 0) {
+        return "No matches found";
+    }
+    const lines = [];
+    let currentFile;
+    for (const match of union.output.matches) {
+        if (match.file !== currentFile) {
+            if (currentFile !== undefined) {
+                lines.push("");
+            }
+            currentFile = match.file;
+            lines.push(match.file);
+        }
+        const before = (_a = match.beforeContext) !== null && _a !== void 0 ? _a : [];
+        const matchLine = (_b = match.lineNumber) !== null && _b !== void 0 ? _b : 1;
+        before.forEach((line, index) => {
+            lines.push(`  ${matchLine - before.length + index}-${line}`);
+        });
+        lines.push(`  ${(_c = match.lineNumber) !== null && _c !== void 0 ? _c : ""}:${match.line}`);
+        ((_d = match.afterContext) !== null && _d !== void 0 ? _d : []).forEach((line, index) => {
+            lines.push(`  ${matchLine + 1 + index}-${line}`);
+        });
+    }
+    return lines.join("\n");
+}
+export function formatWriteOutput(path) {
+    return `Wrote contents to ${path}`;
+}
+export function formatStrReplaceOutput(args) {
+    if (!args.replaceAll) {
+        return `The file ${args.path} has been updated.`;
+    }
+    const occurrenceLabel = args.occurrencesModified === 1 ? "occurrence" : "occurrences";
+    const verb = args.occurrencesModified === 1 ? "has" : "have";
+    return `${args.occurrencesModified} ${occurrenceLabel} in file ${args.path} ${verb} been updated.`;
+}

package/dist/internal/filesystem/merge.d.ts

@@ -0,0 +1,34 @@
+/**
+ * K-way merge of already-sorted streams. Each source must be ordered
+ * under the same `compare`; the merge does not re-sort a source.
+ *
+ * A binary heap of heads keeps the next yield O(log k) in the number of
+ * sources. `unique` skips later copies of a key so an earlier source can
+ * shadow a later one (the union rule).
+ */
+export interface MergeSortedOptions<T> {
+    compare: (left: T, right: T) => number;
+    unique?: boolean;
+}
+/**
+ * Merge already-sorted iterables / async iterables under `compare`.
+ * Equal keys (`compare === 0`) keep source order: earlier `sources`
+ * index wins. With `unique`, those later copies are skipped.
+ */
+export declare function mergeSorted<T>(sources: Array<Iterable<T> | AsyncIterable<T>>, options: MergeSortedOptions<T>): AsyncGenerator<T>;
+/**
+ * Binary min-heap. `compare(a, b) < 0` means `a` is before `b`.
+ * Exported for the invariant tests; composers use {@link mergeSorted}.
+ */
+export declare class MinHeap<T> {
+    private readonly compare;
+    private readonly items;
+    constructor(compare: (left: T, right: T) => number);
+    get size(): number;
+    peek(): T | undefined;
+    push(item: T): void;
+    pop(): T | undefined;
+    private bubbleUp;
+    private bubbleDown;
+}
+//# sourceMappingURL=merge.d.ts.map

package/dist/internal/filesystem/merge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge.d.ts","sourceRoot":"","sources":["../../../src/internal/filesystem/merge.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,WAAW,kBAAkB,CAAC,CAAC;IACnC,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,KAAK,MAAM,CAAC;IACvC,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAQD;;;;GAIG;AACH,wBAAuB,WAAW,CAAC,CAAC,EAClC,OAAO,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC,EAC9C,OAAO,EAAE,kBAAkB,CAAC,CAAC,CAAC,GAC7B,cAAc,CAAC,CAAC,CAAC,CAsCnB;AAiCD;;;GAGG;AACH,qBAAa,OAAO,CAAC,CAAC;IAGR,OAAO,CAAC,QAAQ,CAAC,OAAO;IAFpC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAW;IAEjC,YAA6B,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,KAAK,MAAM,EAAI;IAEvE,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,IAAI,IAAI,CAAC,GAAG,SAAS,CAEpB;IAED,IAAI,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI,CAGlB;IAED,GAAG,IAAI,CAAC,GAAG,SAAS,CAYnB;IAED,OAAO,CAAC,QAAQ;IAmBhB,OAAO,CAAC,UAAU;CAqCnB"}

package/dist/internal/filesystem/merge.js

@@ -0,0 +1,196 @@
+/**
+ * K-way merge of already-sorted streams. Each source must be ordered
+ * under the same `compare`; the merge does not re-sort a source.
+ *
+ * A binary heap of heads keeps the next yield O(log k) in the number of
+ * sources. `unique` skips later copies of a key so an earlier source can
+ * shadow a later one (the union rule).
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __asyncValues = (this && this.__asyncValues) || function (o) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var m = o[Symbol.asyncIterator], i;
+    return m ? m.call(o) : (o = typeof __values === "function" ? __values(o) : o[Symbol.iterator](), i = {}, verb("next"), verb("throw"), verb("return"), i[Symbol.asyncIterator] = function () { return this; }, i);
+    function verb(n) { i[n] = o[n] && function (v) { return new Promise(function (resolve, reject) { v = o[n](v), settle(resolve, reject, v.done, v.value); }); }; }
+    function settle(resolve, reject, d, v) { Promise.resolve(v).then(function(v) { resolve({ value: v, done: d }); }, reject); }
+};
+var __await = (this && this.__await) || function (v) { return this instanceof __await ? (this.v = v, this) : new __await(v); }
+var __asyncDelegator = (this && this.__asyncDelegator) || function (o) {
+    var i, p;
+    return i = {}, verb("next"), verb("throw", function (e) { throw e; }), verb("return"), i[Symbol.iterator] = function () { return this; }, i;
+    function verb(n, f) { i[n] = o[n] ? function (v) { return (p = !p) ? { value: __await(o[n](v)), done: false } : f ? f(v) : v; } : f; }
+};
+var __asyncGenerator = (this && this.__asyncGenerator) || function (thisArg, _arguments, generator) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var g = generator.apply(thisArg, _arguments || []), i, q = [];
+    return i = Object.create((typeof AsyncIterator === "function" ? AsyncIterator : Object).prototype), verb("next"), verb("throw"), verb("return", awaitReturn), i[Symbol.asyncIterator] = function () { return this; }, i;
+    function awaitReturn(f) { return function (v) { return Promise.resolve(v).then(f, reject); }; }
+    function verb(n, f) { if (g[n]) { i[n] = function (v) { return new Promise(function (a, b) { q.push([n, v, a, b]) > 1 || resume(n, v); }); }; if (f) i[n] = f(i[n]); } }
+    function resume(n, v) { try { step(g[n](v)); } catch (e) { settle(q[0][3], e); } }
+    function step(r) { r.value instanceof __await ? Promise.resolve(r.value.v).then(fulfill, reject) : settle(q[0][2], r); }
+    function fulfill(value) { resume("next", value); }
+    function reject(value) { resume("throw", value); }
+    function settle(f, v) { if (f(v), q.shift(), q.length) resume(q[0][0], q[0][1]); }
+};
+/**
+ * Merge already-sorted iterables / async iterables under `compare`.
+ * Equal keys (`compare === 0`) keep source order: earlier `sources`
+ * index wins. With `unique`, those later copies are skipped.
+ */
+export function mergeSorted(sources, options) {
+    return __asyncGenerator(this, arguments, function* mergeSorted_1() {
+        const { compare, unique = false } = options;
+        const heap = new MinHeap((left, right) => {
+            const byValue = compare(left.value, right.value);
+            return byValue !== 0 ? byValue : left.source - right.source;
+        });
+        const iterators = sources.map((source, sourceIndex) => {
+            const iterator = Symbol.asyncIterator in source
+                ? source[Symbol.asyncIterator]()
+                : (function () {
+                    return __asyncGenerator(this, arguments, function* () {
+                        yield __await(yield* __asyncDelegator(__asyncValues(source)));
+                    });
+                })();
+            return { iterator, sourceIndex };
+        });
+        yield __await(Promise.all(iterators.map((_a) => __awaiter(this, [_a], void 0, function* ({ iterator, sourceIndex }) {
+            const next = yield iterator.next();
+            if (!next.done) {
+                heap.push({ value: next.value, iterator, source: sourceIndex });
+            }
+        }))));
+        while (heap.size > 0) {
+            const best = heap.pop();
+            if (best === undefined) {
+                return yield __await(void 0);
+            }
+            yield yield __await(best.value);
+            if (unique) {
+                yield __await(advanceMatching(heap, best, compare));
+            }
+            else {
+                yield __await(pushNext(heap, best));
+            }
+        }
+    });
+}
+function pushNext(heap, head) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const next = yield head.iterator.next();
+        if (!next.done) {
+            heap.push({
+                value: next.value,
+                iterator: head.iterator,
+                source: head.source,
+            });
+        }
+    });
+}
+/** Advance every head whose key equals `best` (compare === 0). */
+function advanceMatching(heap, best, compare) {
+    return __awaiter(this, void 0, void 0, function* () {
+        yield pushNext(heap, best);
+        while (heap.size > 0) {
+            const peek = heap.peek();
+            if (peek === undefined || compare(peek.value, best.value) !== 0) {
+                return;
+            }
+            const duplicate = heap.pop();
+            if (duplicate === undefined) {
+                return;
+            }
+            yield pushNext(heap, duplicate);
+        }
+    });
+}
+/**
+ * Binary min-heap. `compare(a, b) < 0` means `a` is before `b`.
+ * Exported for the invariant tests; composers use {@link mergeSorted}.
+ */
+export class MinHeap {
+    constructor(compare) {
+        this.compare = compare;
+        this.items = [];
+    }
+    get size() {
+        return this.items.length;
+    }
+    peek() {
+        return this.items[0];
+    }
+    push(item) {
+        this.items.push(item);
+        this.bubbleUp(this.items.length - 1);
+    }
+    pop() {
+        const first = this.items[0];
+        if (first === undefined) {
+            return undefined;
+        }
+        const last = this.items.pop();
+        if (last === undefined || this.items.length === 0) {
+            return first;
+        }
+        this.items[0] = last;
+        this.bubbleDown(0);
+        return first;
+    }
+    bubbleUp(index) {
+        let current = index;
+        while (current > 0) {
+            const parent = Math.floor((current - 1) / 2);
+            const parentItem = this.items[parent];
+            const currentItem = this.items[current];
+            if (parentItem === undefined ||
+                currentItem === undefined ||
+                this.compare(currentItem, parentItem) >= 0) {
+                return;
+            }
+            this.items[parent] = currentItem;
+            this.items[current] = parentItem;
+            current = parent;
+        }
+    }
+    bubbleDown(index) {
+        let current = index;
+        for (;;) {
+            const left = current * 2 + 1;
+            const right = left + 1;
+            let smallest = current;
+            const currentItem = this.items[smallest];
+            const leftItem = this.items[left];
+            if (leftItem !== undefined &&
+                currentItem !== undefined &&
+                this.compare(leftItem, currentItem) < 0) {
+                smallest = left;
+            }
+            const smallestItem = this.items[smallest];
+            const rightItem = this.items[right];
+            if (rightItem !== undefined &&
+                smallestItem !== undefined &&
+                this.compare(rightItem, smallestItem) < 0) {
+                smallest = right;
+            }
+            if (smallest === current) {
+                return;
+            }
+            const swapCurrent = this.items[current];
+            const swapSmallest = this.items[smallest];
+            if (swapCurrent === undefined || swapSmallest === undefined) {
+                return;
+            }
+            this.items[current] = swapSmallest;
+            this.items[smallest] = swapCurrent;
+            current = smallest;
+        }
+    }
+}

package/dist/internal/filesystem/nearest.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Parent-listing neighbors for a Read / LS miss. FileSystem has no
+ * catalog API; `list(dirname(path))` is the sibling set. Immediate
+ * children only — a recursive mount must not dump its whole subtree.
+ */
+import type { FileSystem } from "../../filesystem.js";
+export declare function nearestListedNames(query: string, names: readonly string[], limit?: number): string[];
+export declare function formatMissNeighborHint(path: string, neighbors: readonly string[]): string | undefined;
+/**
+ * One-line miss hint when the parent directory listed siblings.
+ * `undefined` leaves the caller to throw the ordinary miss.
+ */
+export declare function nearestNeighborMissHint(root: Pick<FileSystem, "list">, path: string): Promise<string | undefined>;
+//# sourceMappingURL=nearest.d.ts.map

package/dist/internal/filesystem/nearest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nearest.d.ts","sourceRoot":"","sources":["../../../src/internal/filesystem/nearest.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAMtD,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,KAAK,GAAE,MAAuB,GAC7B,MAAM,EAAE,CAeV;AAED,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,SAAS,MAAM,EAAE,GAC3B,MAAM,GAAG,SAAS,CAKpB;AAED;;;GAGG;AACH,wBAAsB,uBAAuB,CAC3C,IAAI,EAAE,IAAI,CAAC,UAAU,EAAE,MAAM,CAAC,EAC9B,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAc7B"}