@cursor/july 0.1.102 → 0.1.104

package/src/internal/filesystem/walk.ts

@@ -0,0 +1,369 @@
+/**
+ * Recursive listing, existence probes, and native LS trees. Matches the
+ * change-monitor VFS contract on origin/main: `list` is files-only and
+ * recursive; `stat` tells file / directory / missing apart; composers
+ * merge already-sorted streams with a k-way heap.
+ */
+
+import { posix } from "node:path";
+import { minimatch } from "minimatch";
+import type { DirEntry, FileInfo, FileSystem } from "../../filesystem.js";
+import { normalizeFsPath } from "../../filesystem.js";
+import { mergeSorted } from "./merge.js";
+
+/**
+ * Native LS `directoryTreeRoot` (LocalLsExecutor ingest tree).
+ * Synthesis builds this from `list` + `stat` via `buildLsTree`.
+ * Not a FileSystem method result and not part of the public
+ * Agent SDK surface.
+ */
+export interface LsDirectoryTreeNode {
+  absPath: string;
+  childrenDirs: LsDirectoryTreeNode[];
+  childrenFiles: Array<{ name: string }>;
+  childrenWereProcessed: boolean;
+  fullSubtreeExtensionCounts: Record<string, number>;
+  numFiles: number;
+}
+
+/** Filename-character ingest budget; matches LocalLsExecutor. */
+export const LS_INGEST_CHARACTER_BUDGET = 2_500;
+
+/**
+ * Yield the files under `prefix`, sorted. A file whose path equals
+ * `prefix` is not under itself.
+ */
+export async function* listFilesFromPaths(
+  files: Iterable<DirEntry>,
+  prefix?: string
+): AsyncGenerator<DirEntry> {
+  const scope = normalizeListPrefix(prefix);
+  const withSlash = scope === "/" ? "/" : `${scope}/`;
+  const matches: DirEntry[] = [];
+  for (const file of files) {
+    const filePath = normalizeFsPath(file.path);
+    if (scope === "/") {
+      matches.push(
+        file.size === undefined
+          ? { path: filePath }
+          : { path: filePath, size: file.size }
+      );
+      continue;
+    }
+    if (filePath === scope || !filePath.startsWith(withSlash)) {
+      continue;
+    }
+    matches.push(
+      file.size === undefined
+        ? { path: filePath }
+        : { path: filePath, size: file.size }
+    );
+  }
+  matches.sort((left, right) => left.path.localeCompare(right.path));
+  yield* matches;
+}
+
+export function normalizeListPrefix(prefix?: string): string {
+  if (prefix === undefined || prefix === "" || prefix === "/") {
+    return "/";
+  }
+  return normalizeFsPath(prefix);
+}
+
+/**
+ * Existence probe over a flat file-path index. Exact key → file; any
+ * key with this prefix → directory; `""` / `/` → directory; else missing.
+ */
+export function statFromFilePaths(
+  files: Iterable<string>,
+  path: string
+): FileInfo {
+  const normalized = normalizeListPrefix(path);
+  if (normalized === "/") {
+    return { kind: "directory" };
+  }
+  const prefix = `${normalized}/`;
+  for (const file of files) {
+    const filePath = normalizeFsPath(file);
+    if (filePath === normalized) {
+      return { kind: "file" };
+    }
+    if (filePath.startsWith(prefix)) {
+      return { kind: "directory" };
+    }
+  }
+  return { kind: "missing" };
+}
+
+export async function collectList(
+  root: Pick<FileSystem, "list">,
+  prefix?: string
+): Promise<DirEntry[]> {
+  const entries: DirEntry[] = [];
+  if (root.list === undefined) {
+    return entries;
+  }
+  for await (const entry of root.list(prefix)) {
+    entries.push(entry);
+  }
+  return entries;
+}
+
+export async function collectGlob(
+  root: Pick<FileSystem, "glob">,
+  options: { pattern: string; dir?: string }
+): Promise<DirEntry[]> {
+  const entries: DirEntry[] = [];
+  if (root.glob === undefined) {
+    return entries;
+  }
+  for await (const entry of root.glob(options.pattern, options.dir)) {
+    entries.push(entry);
+  }
+  return entries;
+}
+
+/**
+ * List, then `stat` only when nothing came back. A non-empty listing is
+ * already a directory (a file is not under itself).
+ */
+export async function collectListOrStat(
+  root: Pick<FileSystem, "list" | "stat">,
+  path?: string
+): Promise<{ kind: FileInfo["kind"]; files: DirEntry[] }> {
+  const files = await collectList(root, path);
+  if (files.length > 0) {
+    return { kind: "directory", files };
+  }
+  if (root.stat === undefined) {
+    return { kind: "missing", files };
+  }
+  const probe = path === undefined || path === "" ? "." : path;
+  return { kind: (await root.stat(probe)).kind, files };
+}
+
+export async function* mergeSortedByPath(
+  sources: Array<Iterable<DirEntry> | AsyncIterable<DirEntry>>,
+  options?: { unique?: boolean }
+): AsyncGenerator<DirEntry> {
+  yield* mergeSorted(sources, {
+    compare: (left, right) => left.path.localeCompare(right.path),
+    unique: options?.unique === true,
+  });
+}
+
+function emptyLsNode(absPath: string): LsDirectoryTreeNode {
+  return {
+    absPath,
+    childrenDirs: [],
+    childrenFiles: [],
+    childrenWereProcessed: true,
+    fullSubtreeExtensionCounts: {},
+    numFiles: 0,
+  };
+}
+
+/**
+ * Build the native LS tree from a recursive file listing. Applies the
+ * LocalLsExecutor ingest budget so a huge directory truncates the same way.
+ */
+export function buildLsTree(
+  dir: string,
+  files: readonly DirEntry[]
+): LsDirectoryTreeNode {
+  const rootPath = normalizeListPrefix(dir);
+  const root: LsDirectoryTreeNode = emptyLsNode(rootPath);
+  const dirNodes = new Map<string, LsDirectoryTreeNode>([[rootPath, root]]);
+  const state = {
+    charactersUsed: rootPath.length,
+    budgetExceeded: false,
+  };
+  for (const file of files) {
+    addPathToTree(
+      file.path,
+      rootPath,
+      dirNodes,
+      state,
+      LS_INGEST_CHARACTER_BUDGET
+    );
+  }
+  return root;
+}
+
+function addPathToTree(
+  filePath: string,
+  rootPath: string,
+  dirNodes: Map<string, LsDirectoryTreeNode>,
+  state: { charactersUsed: number; budgetExceeded: boolean },
+  characterBudget: number
+): void {
+  const fileName = posix.basename(filePath);
+  const dirPath = posixParent(filePath);
+  ensureDirectoryPath(dirPath, rootPath, dirNodes, state.budgetExceeded);
+  const parentNode = dirNodes.get(dirPath);
+  if (parentNode === undefined) {
+    return;
+  }
+  const fileCharCost = fileName.length;
+  if (
+    !state.budgetExceeded &&
+    state.charactersUsed + fileCharCost <= characterBudget
+  ) {
+    parentNode.childrenFiles.push({ name: fileName });
+    state.charactersUsed += fileCharCost;
+    return;
+  }
+  if (!state.budgetExceeded) {
+    state.budgetExceeded = true;
+    let currentDir = dirPath;
+    while (currentDir.startsWith(rootPath)) {
+      const node = dirNodes.get(currentDir);
+      if (node !== undefined) {
+        node.childrenWereProcessed = false;
+      }
+      const parentDir = posixParent(currentDir);
+      if (parentDir === currentDir) {
+        break;
+      }
+      currentDir = parentDir;
+    }
+  }
+  const extension = posix.extname(filePath);
+  let currentDir = dirPath;
+  while (currentDir.startsWith(rootPath)) {
+    const node = dirNodes.get(currentDir);
+    if (node !== undefined) {
+      node.fullSubtreeExtensionCounts[extension] =
+        (node.fullSubtreeExtensionCounts[extension] ?? 0) + 1;
+      node.numFiles += 1;
+    }
+    const parentDir = posixParent(currentDir);
+    if (parentDir === currentDir) {
+      break;
+    }
+    currentDir = parentDir;
+  }
+}
+
+function ensureDirectoryPath(
+  dirPath: string,
+  rootPath: string,
+  dirNodes: Map<string, LsDirectoryTreeNode>,
+  budgetExceeded: boolean
+): void {
+  if (dirNodes.has(dirPath) || dirPath === rootPath) {
+    return;
+  }
+  const parentPath = posixParent(dirPath);
+  if (parentPath !== dirPath && pathIsUnderRoot(parentPath, rootPath)) {
+    ensureDirectoryPath(parentPath, rootPath, dirNodes, budgetExceeded);
+  }
+  const dirNode: LsDirectoryTreeNode = {
+    ...emptyLsNode(dirPath),
+    childrenWereProcessed: !budgetExceeded,
+  };
+  dirNodes.set(dirPath, dirNode);
+  const parentNode = dirNodes.get(parentPath);
+  if (parentNode !== undefined) {
+    parentNode.childrenDirs.push(dirNode);
+  }
+}
+
+function pathIsUnderRoot(path: string, rootPath: string): boolean {
+  return (
+    path === rootPath ||
+    path.startsWith(rootPath === "/" ? "/" : `${rootPath}/`)
+  );
+}
+
+/**
+ * Native LS ignore_globs: a pattern that is not already recursive is
+ * matched at any depth (the same `** /` prefix the Cursor SDK native uses).
+ */
+export function applyIgnores(
+  entries: readonly DirEntry[],
+  ignoreGlobs?: readonly string[]
+): DirEntry[] {
+  if (ignoreGlobs === undefined || ignoreGlobs.length === 0) {
+    return [...entries];
+  }
+  return entries.filter(
+    (entry) => !ignoreGlobs.some((glob) => matchesIgnoreGlob(entry.path, glob))
+  );
+}
+
+function matchesIgnoreGlob(filePath: string, glob: string): boolean {
+  const recursivePrefix = "**".concat("/");
+  const pattern = glob.startsWith(recursivePrefix)
+    ? glob
+    : recursivePrefix + glob;
+  const relative = filePath.replace(/^\//, "");
+  return (
+    minimatch(relative, pattern, { dot: true }) ||
+    minimatch(filePath, pattern, { dot: true })
+  );
+}
+
+export async function lsFromList(
+  root: Pick<FileSystem, "list" | "stat">,
+  path?: string,
+  ignoreGlobs?: readonly string[]
+): Promise<
+  | { status: "success"; value: { directoryTreeRoot: LsDirectoryTreeNode } }
+  | { status: "error"; error: { message: string } }
+> {
+  const listed = await collectListOrStat(root, path);
+  const treePath = path ?? inferListedRoot(listed.files);
+  switch (listed.kind) {
+    case "missing":
+      return {
+        status: "error",
+        error: { message: `Path does not exist: ${treePath}` },
+      };
+    case "file":
+      return {
+        status: "error",
+        error: { message: `Path is not a directory: ${treePath}` },
+      };
+    case "directory":
+      return {
+        status: "success",
+        value: {
+          directoryTreeRoot: buildLsTree(
+            treePath,
+            applyIgnores(listed.files, ignoreGlobs)
+          ),
+        },
+      };
+  }
+}
+
+function inferListedRoot(files: readonly DirEntry[]): string {
+  if (files.length === 0) {
+    return "/";
+  }
+  let prefix = posixParent(files[0]!.path);
+  for (const file of files) {
+    while (
+      prefix !== "/" &&
+      file.path !== prefix &&
+      !file.path.startsWith(`${prefix}/`)
+    ) {
+      const parent = posixParent(prefix);
+      if (parent === prefix) {
+        return "/";
+      }
+      prefix = parent;
+    }
+  }
+  return prefix;
+}
+
+/**
+ * `path.posix.dirname` returns `.` for slash-free paths. Treat that as
+ * the virtual root so LS walks terminate and relative files attach to `/`.
+ */
+function posixParent(path: string): string {
+  const dir = posix.dirname(path);
+  return dir === "." || dir === path ? "/" : dir;
+}

package/src/internal/framework-file-storage.ts

@@ -71,14 +71,6 @@ export type FileSinkStorageCore = Required<
   Pick<StorageConfig, "put" | "get" | "delete" | "list">
 >;
 
-/**
- * Adapt a {@link FileSink} to the `defineStorage` KV core. Storage keys are
- * framework-minted (URI-encoded, length-bounded segments — see
- * {@link storageKeys}), so they are used as file keys verbatim; values are
- * stored as JSON bytes. Parse failures throw: on the lazy-restore path a
- * corrupt document must fail the follow-up rather than read as a miss, and
- * the startup bulk restore already logs-and-skips a throwing `list`.
- */
 /** Parallel per-key reads backing `list` (each is presign + object GET). */
 const LIST_READ_CONCURRENCY = 8;
 
@@ -95,6 +87,14 @@ function isUnrepresentableFileKey(key: string): boolean {
     .some((segment) => segment === "" || segment === "." || segment === "..");
 }
 
+/**
+ * Adapt a {@link FileSink} to the `defineStorage` KV core. Storage keys are
+ * framework-minted (URI-encoded, length-bounded segments — see
+ * {@link storageKeys}), so they are used as file keys verbatim; values are
+ * stored as JSON bytes. Parse failures throw: on the lazy-restore path a
+ * corrupt document must fail the follow-up rather than read as a miss, and
+ * the startup bulk restore already logs-and-skips a throwing `list`.
+ */
 export function fileSinkStorageCore(sink: FileSink): FileSinkStorageCore {
   return {
     async put(key, value): Promise<void> {

package/src/internal/github-fanout.ts

@@ -1,5 +1,5 @@
 /**
- * Local fan-out proxy for `agent-serve github forward`.
+ * Local fan-out proxy for `agent-sdk github forward`.
  *
  * `gh webhook forward` can only target a single URL, and GitHub allows just one
  * forwarder per repo/org. To feed several GitHub channels at once, we run one