@cursor/july 0.1.103 → 0.1.105

package/src/internal/filesystem/errors.ts

@@ -0,0 +1,220 @@
+/**
+ * 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: string): string {
+  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: string,
+  from: string,
+  to: string
+): string {
+  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 {
+  readonly path: string;
+
+  constructor(path: string, message: string) {
+    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: string): this {
+    const next = normalizeErrorPath(path);
+    if (next === this.path) {
+      return this;
+    }
+    return this.recreate(
+      next,
+      rewritePathInMessage(this.message, this.path, next)
+    );
+  }
+
+  protected recreate(path: string, message: string): this {
+    return new PathError(path, message) as this;
+  }
+}
+
+export class FileNotFoundError extends PathError {
+  constructor(path: string, message?: string) {
+    super(path, message ?? `not found: ${normalizeErrorPath(path)}`);
+  }
+
+  protected override recreate(path: string, message: string): this {
+    return new FileNotFoundError(path, message) as this;
+  }
+}
+
+export class ReadOnlyMountError extends PathError {
+  constructor(path: string, message?: string) {
+    super(path, message ?? `read-only mount: ${normalizeErrorPath(path)}`);
+  }
+
+  protected override recreate(path: string, message: string): this {
+    return new ReadOnlyMountError(path, message) as this;
+  }
+}
+
+export class NoMountError extends PathError {
+  constructor(path: string, message?: string) {
+    super(path, message ?? `no mount for path: ${normalizeErrorPath(path)}`);
+  }
+
+  protected override recreate(path: string, message: string): this {
+    return new NoMountError(path, message) as this;
+  }
+}
+
+export class WriteFailedError extends PathError {
+  constructor(path: string, message?: string) {
+    super(path, message ?? `write failed: ${normalizeErrorPath(path)}`);
+  }
+
+  protected override recreate(path: string, message: string): this {
+    return new WriteFailedError(path, message) as this;
+  }
+}
+
+export class DeleteNotSupportedError extends PathError {
+  constructor(path: string, message?: string) {
+    super(
+      path,
+      message ?? `delete is not supported: ${normalizeErrorPath(path)}`
+    );
+  }
+
+  protected override recreate(path: string, message: string): this {
+    return new DeleteNotSupportedError(path, message) as this;
+  }
+}
+
+/**
+ * Exact-edit contract failures (`oldText is empty`, uniqueness).
+ * `message` is the contract string; it does not embed `path`.
+ */
+export class EditError extends PathError {
+  protected override recreate(path: string, message: string): this {
+    return new EditError(path, message) as this;
+  }
+}
+
+export class InvalidGrepPatternError extends PathError {
+  readonly pattern: string;
+
+  constructor(pattern: string, path = "/", message?: string) {
+    super(path, message ?? `invalid grep pattern: ${pattern}`);
+    this.pattern = pattern;
+  }
+
+  protected override recreate(path: string, message: string): this {
+    return new InvalidGrepPatternError(this.pattern, path, message) as this;
+  }
+}
+
+export function isFileNotFoundError(error: unknown): boolean {
+  return (
+    error instanceof FileNotFoundError ||
+    (error instanceof Error && error.message.startsWith("not found:"))
+  );
+}
+
+export function isInvalidGrepPatternError(error: unknown): boolean {
+  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: ",
+] as const;
+
+/**
+ * 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: unknown, prefix: string): Error {
+  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: string, prefix: string): string {
+  const mount = normalizeErrorPath(prefix);
+  const child = normalizeErrorPath(childPath);
+  if (mount === "/") {
+    return child;
+  }
+  if (child === "/") {
+    return mount;
+  }
+  return `${mount}${child}`;
+}
+
+function rewriteUntypedMountError(error: Error, prefix: string): Error {
+  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/src/internal/filesystem/format.ts

@@ -0,0 +1,276 @@
+/**
+ * Model-facing strings that match Cursor SDK native tool output
+ * (LocalLsExecutor / read / grep / glob formatters).
+ */
+
+import { posix } from "node:path";
+
+import type { GrepUnionResult } from "../../filesystem.js";
+import type { LsDirectoryTreeNode } from "./walk.js";
+
+const LS_RENDER_CHARACTER_BUDGET = 10_000;
+const GLOB_TOTAL_CHARACTER_BUDGET = 5_000;
+
+/**
+ * Number already-sliced Read content. `FileSystem.read` applies offset/
+ * limit; do not window again or line numbers restart at 1.
+ */
+export function slicedReadStartLine(
+  totalLines: number,
+  offset?: number
+): number {
+  if (offset === undefined) {
+    return 1;
+  }
+  if (offset < 0) {
+    return Math.max(1, totalLines + offset + 1);
+  }
+  return Math.max(1, offset);
+}
+
+export 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 {
+  const lines = content === "" ? [] : content.split("\n");
+  if (lines.length === 0) {
+    return "";
+  }
+  const { offset, limit, startLine } = options;
+  let start = 1;
+  let window = lines;
+  const total = options.totalLines ?? lines.length;
+  if (startLine !== undefined) {
+    start = startLine;
+  } else if (offset !== undefined || limit !== undefined) {
+    const effectiveOffset = offset ?? 1;
+    const effectiveLimit =
+      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: readonly string[],
+  start: number,
+  total: number
+): string {
+  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: LsDirectoryTreeNode): string {
+  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: string[] = [];
+  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: LsDirectoryTreeNode,
+  renderExtensionCounts = true,
+  renderDepthLimit?: number
+): { result: string } {
+  function render(dir: LsDirectoryTreeNode, depth: number): string {
+    const indent = "  ".repeat(depth);
+    let result: string;
+    if (depth === 0) {
+      const trailingSep = dir.absPath.endsWith("/") ? "" : "/";
+      result = `${dir.absPath}${trailingSep}\n`;
+    } else {
+      result = `${indent}- ${posix.basename(dir.absPath)}/\n`;
+    }
+
+    type LsChild =
+      | { type: "file"; name: string }
+      | { type: "dir"; name: string; dir: LsDirectoryTreeNode };
+    const allChildren: LsChild[] = [
+      ...dir.childrenFiles.map(
+        (file): LsChild => ({ type: "file", name: file.name })
+      ),
+      ...dir.childrenDirs.map(
+        (childDir): LsChild => ({
+          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: string,
+  files: readonly string[]
+): string {
+  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 = relative[i] ?? "";
+    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: GrepUnionResult | undefined): string {
+  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: string[] = [];
+  let currentFile: string | undefined;
+  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 = match.beforeContext ?? [];
+    const matchLine = match.lineNumber ?? 1;
+    before.forEach((line, index) => {
+      lines.push(`  ${matchLine - before.length + index}-${line}`);
+    });
+    lines.push(`  ${match.lineNumber ?? ""}:${match.line}`);
+    (match.afterContext ?? []).forEach((line, index) => {
+      lines.push(`  ${matchLine + 1 + index}-${line}`);
+    });
+  }
+  return lines.join("\n");
+}
+
+export function formatWriteOutput(path: string): string {
+  return `Wrote contents to ${path}`;
+}
+
+export function formatStrReplaceOutput(args: {
+  path: string;
+  replaceAll: boolean;
+  occurrencesModified: number;
+}): string {
+  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/src/internal/filesystem/merge.ts

@@ -0,0 +1,195 @@
+/**
+ * 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;
+}
+
+type Head<T> = {
+  value: T;
+  iterator: AsyncIterator<T>;
+  source: number;
+};
+
+/**
+ * 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 async function* mergeSorted<T>(
+  sources: Array<Iterable<T> | AsyncIterable<T>>,
+  options: MergeSortedOptions<T>
+): AsyncGenerator<T> {
+  const { compare, unique = false } = options;
+  const heap = new MinHeap<Head<T>>((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]()
+        : (async function* () {
+            yield* source;
+          })();
+    return { iterator, sourceIndex };
+  });
+
+  await Promise.all(
+    iterators.map(async ({ iterator, sourceIndex }) => {
+      const next = await 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 best.value;
+    if (unique) {
+      await advanceMatching(heap, best, compare);
+    } else {
+      await pushNext(heap, best);
+    }
+  }
+}
+
+async function pushNext<T>(
+  heap: MinHeap<Head<T>>,
+  head: Head<T>
+): Promise<void> {
+  const next = await 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). */
+async function advanceMatching<T>(
+  heap: MinHeap<Head<T>>,
+  best: Head<T>,
+  compare: (left: T, right: T) => number
+): Promise<void> {
+  await 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;
+    }
+    await 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<T> {
+  private readonly items: T[] = [];
+
+  constructor(private readonly compare: (left: T, right: T) => number) {}
+
+  get size(): number {
+    return this.items.length;
+  }
+
+  peek(): T | undefined {
+    return this.items[0];
+  }
+
+  push(item: T): void {
+    this.items.push(item);
+    this.bubbleUp(this.items.length - 1);
+  }
+
+  pop(): T | undefined {
+    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;
+  }
+
+  private bubbleUp(index: number): void {
+    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;
+    }
+  }
+
+  private bubbleDown(index: number): void {
+    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;
+    }
+  }
+}