@vellumai/assistant 0.12.1 → 0.12.2-staging.1

package/src/runtime/routes/workspace-routes.test.ts

@@ -211,8 +211,8 @@ describe("isTextMimeType", () => {
 describe("GET /v1/workspace/tree", () => {
   const { handler } = getRoute("workspace_tree");
 
-  test("root listing returns entries", () => {
-    const result = handler({ queryParams: {} }) as {
+  test("root listing returns entries", async () => {
+    const result = (await handler({ queryParams: {} })) as {
       path: string;
       entries: Array<{ name: string; type: string }>;
     };
@@ -222,8 +222,8 @@ describe("GET /v1/workspace/tree", () => {
     expect(names).toContain("subdir");
   });
 
-  test("subdirectory listing returns child entries", () => {
-    const result = handler({ queryParams: { path: "subdir" } }) as {
+  test("subdirectory listing returns child entries", async () => {
+    const result = (await handler({ queryParams: { path: "subdir" } })) as {
       path: string;
       entries: Array<{ name: string; type: string }>;
     };
@@ -232,20 +232,20 @@ describe("GET /v1/workspace/tree", () => {
     expect(result.entries[0].type).toBe("file");
   });
 
-  test("non-existent directory throws NotFoundError", () => {
-    expect(() => handler({ queryParams: { path: "nope" } })).toThrow(
+  test("non-existent directory throws NotFoundError", async () => {
+    await expect(handler({ queryParams: { path: "nope" } })).rejects.toThrow(
       NotFoundError,
     );
   });
 
-  test("path traversal attempt throws BadRequestError", () => {
-    expect(() => handler({ queryParams: { path: "../../etc" } })).toThrow(
-      BadRequestError,
-    );
+  test("path traversal attempt throws BadRequestError", async () => {
+    await expect(
+      handler({ queryParams: { path: "../../etc" } }),
+    ).rejects.toThrow(BadRequestError);
   });
 
-  test("entries have correct type field", () => {
-    const result = handler({ queryParams: {} }) as {
+  test("entries have correct type field", async () => {
+    const result = (await handler({ queryParams: {} })) as {
       entries: Array<{ name: string; type: "file" | "directory" }>;
     };
     const subdirEntry = result.entries.find((e) => e.name === "subdir");
@@ -254,8 +254,8 @@ describe("GET /v1/workspace/tree", () => {
     expect(fileEntry?.type).toBe("file");
   });
 
-  test("dotfiles and dot-directories are excluded", () => {
-    const result = handler({ queryParams: {} }) as {
+  test("dotfiles and dot-directories are excluded", async () => {
+    const result = (await handler({ queryParams: {} })) as {
       entries: Array<{ name: string }>;
     };
     const names = result.entries.map((e) => e.name);
@@ -263,8 +263,8 @@ describe("GET /v1/workspace/tree", () => {
     expect(names).not.toContain(".hidden");
   });
 
-  test("directory entries have null size and mimeType", () => {
-    const result = handler({ queryParams: {} }) as {
+  test("directory entries have null size and mimeType", async () => {
+    const result = (await handler({ queryParams: {} })) as {
       entries: Array<{
         name: string;
         type: string;
@@ -278,8 +278,8 @@ describe("GET /v1/workspace/tree", () => {
     expect(dirEntry!.mimeType).toBeNull();
   });
 
-  test("directories sorted before files", () => {
-    const result = handler({ queryParams: {} }) as {
+  test("directories sorted before files", async () => {
+    const result = (await handler({ queryParams: {} })) as {
       entries: Array<{ type: string }>;
     };
     const firstFileIdx = result.entries.findIndex((e) => e.type === "file");
@@ -295,8 +295,10 @@ describe("GET /v1/workspace/tree", () => {
     }
   });
 
-  test("includeDirSizes=true returns recursive byte size for directories", () => {
-    const result = handler({ queryParams: { includeDirSizes: "true" } }) as {
+  test("includeDirSizes=true returns recursive byte size for directories", async () => {
+    const result = (await handler({
+      queryParams: { includeDirSizes: "true" },
+    })) as {
       entries: Array<{ name: string; type: string; size: number | null }>;
     };
     const subdirEntry = result.entries.find((e) => e.name === "subdir");
@@ -307,8 +309,10 @@ describe("GET /v1/workspace/tree", () => {
     expect(subdirEntry!.size).toBe("nested content".length);
   });
 
-  test("includeDirSizes=true preserves accurate file sizes", () => {
-    const result = handler({ queryParams: { includeDirSizes: "true" } }) as {
+  test("includeDirSizes=true preserves accurate file sizes", async () => {
+    const result = (await handler({
+      queryParams: { includeDirSizes: "true" },
+    })) as {
       entries: Array<{ name: string; type: string; size: number | null }>;
     };
     const fileEntry = result.entries.find((e) => e.name === "hello.txt");
@@ -316,8 +320,8 @@ describe("GET /v1/workspace/tree", () => {
     expect(fileEntry!.size).toBe("Hello, world!".length);
   });
 
-  test("includeDirSizes omitted preserves null size for directories", () => {
-    const result = handler({ queryParams: {} }) as {
+  test("includeDirSizes omitted preserves null size for directories", async () => {
+    const result = (await handler({ queryParams: {} })) as {
       entries: Array<{ type: string; size: number | null }>;
     };
     const dirEntry = result.entries.find((e) => e.type === "directory");
@@ -325,11 +329,36 @@ describe("GET /v1/workspace/tree", () => {
     expect(dirEntry!.size).toBeNull();
   });
 
-  test("includeDirSizes=true returns 0 for empty directory", () => {
+  test("recursive=true lists nested entries and the bound fields", async () => {
+    const result = (await handler({ queryParams: { recursive: "true" } })) as {
+      entries: Array<{ path: string }>;
+      truncated: boolean;
+      skipped: string[];
+    };
+    expect(result.entries.map((e) => e.path)).toContain("subdir/nested.txt");
+    expect(result.truncated).toBe(false);
+    expect(Array.isArray(result.skipped)).toBe(true);
+  });
+
+  test("a non-recursive listing carries the same fields, unset", async () => {
+    const result = (await handler({ queryParams: {} })) as {
+      entries: Array<{ path: string }>;
+      truncated: boolean;
+      skipped: string[];
+    };
+    expect(result.entries.map((e) => e.path)).not.toContain(
+      "subdir/nested.txt",
+    );
+    expect(result).toMatchObject({ truncated: false, skipped: [] });
+  });
+
+  test("includeDirSizes=true returns 0 for empty directory", async () => {
     const emptyDir = join(testWorkspaceDir, "empty-for-size");
     mkdirSync(emptyDir, { recursive: true });
 
-    const result = handler({ queryParams: { includeDirSizes: "true" } }) as {
+    const result = (await handler({
+      queryParams: { includeDirSizes: "true" },
+    })) as {
       entries: Array<{ name: string; size: number | null }>;
     };
     const emptyEntry = result.entries.find((e) => e.name === "empty-for-size");

package/src/runtime/routes/workspace-routes.ts

@@ -30,24 +30,15 @@ import {
 } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 import { RouteResponse } from "./types.js";
+import { walkWorkspaceTree } from "./workspace-tree-walk.js";
 import {
   isTextMimeType,
   MAX_INLINE_TEXT_SIZE,
   resolveWorkspacePath,
+  workspaceEntrySchema,
   writeWorkspaceFile,
 } from "./workspace-utils.js";
 
-const workspaceTreeEntrySchema = z.object({
-  name: z.string(),
-  path: z.string(),
-  type: z.enum(["file", "directory"]),
-  size: z.number().nullable(),
-  mimeType: z.string().nullable(),
-  modifiedAt: z.string(),
-});
-
-type TreeEntry = z.infer<typeof workspaceTreeEntrySchema>;
-
 // Recursive directory sizing walks the filesystem synchronously, so it is
 // bounded by two caps that work together:
 //
@@ -175,10 +166,11 @@ function publishSoundsConfigUpdatedForPaths(
 // GET /v1/workspace/tree — list directory contents
 // ---------------------------------------------------------------------------
 
-function handleWorkspaceTree({ queryParams }: RouteHandlerArgs) {
+async function handleWorkspaceTree({ queryParams }: RouteHandlerArgs) {
   const requestedPath = queryParams?.path ?? "";
   const showHidden = queryParams?.showHidden === "true";
   const includeDirSizes = queryParams?.includeDirSizes === "true";
+  const recursive = queryParams?.recursive === "true";
   const resolved = resolveWorkspacePath(requestedPath, {
     allowHidden: showHidden,
   });
@@ -186,62 +178,36 @@ function handleWorkspaceTree({ queryParams }: RouteHandlerArgs) {
     throw new BadRequestError("Invalid path");
   }
 
-  try {
-    const dirents = readdirSync(resolved, { withFileTypes: true });
-    const workspaceDir = getWorkspaceDir();
-
-    // Listing-wide budget, only constructed when sizes are requested. Each
-    // directory draws a per-directory allotment from it so one oversized
-    // subtree can't starve its siblings, while the shared remainder still caps
-    // total synchronous traversal for the whole listing.
-    const listingBudget: DirSizeBudget | undefined = includeDirSizes
+  // Listing-wide budget, only constructed when sizes are requested. Each
+  // directory draws a per-directory allotment from it so one oversized
+  // subtree can't starve its siblings, while the shared remainder still caps
+  // total synchronous traversal for the whole listing.
+  const listingBudget: DirSizeBudget | undefined =
+    includeDirSizes && !recursive
       ? { remaining: DIR_SIZE_TOTAL_ENTRY_BUDGET }
       : undefined;
 
-    const entries: TreeEntry[] = [];
-    for (const entry of dirents) {
-      if (!showHidden && entry.name.startsWith(".")) {
-        continue;
-      }
-
-      const fullPath = join(resolved, entry.name);
-
-      let stats: ReturnType<typeof statSync>;
-      try {
-        stats = statSync(fullPath);
-      } catch {
-        continue;
-      }
-
-      const isDir = stats.isDirectory();
-      const relativePath = fullPath.slice(workspaceDir.length + 1);
-
-      const dirSize =
-        isDir && listingBudget
-          ? computeDirSizeWithinListing(fullPath, listingBudget)
-          : null;
-
-      entries.push({
-        name: entry.name,
-        path: relativePath,
-        type: isDir ? "directory" : "file",
-        size: isDir ? dirSize : stats.size,
-        mimeType: isDir ? null : Bun.file(fullPath).type,
-        modifiedAt: stats.mtime.toISOString(),
-      });
-    }
-
-    entries.sort((a, b) => {
-      if (a.type !== b.type) {
-        return a.type === "directory" ? -1 : 1;
-      }
-      return a.name.localeCompare(b.name);
+  let walk: Awaited<ReturnType<typeof walkWorkspaceTree>>;
+  try {
+    walk = await walkWorkspaceTree({
+      rootPath: resolved,
+      workspaceDir: getWorkspaceDir(),
+      showHidden,
+      recursive,
+      directorySize: listingBudget
+        ? (absPath) => computeDirSizeWithinListing(absPath, listingBudget)
+        : undefined,
     });
-
-    return { path: requestedPath, entries };
   } catch {
     throw new NotFoundError("Directory not found");
   }
+
+  return {
+    path: requestedPath,
+    entries: walk.entries,
+    truncated: walk.truncated,
+    skipped: walk.skipped,
+  };
 }
 
 // ---------------------------------------------------------------------------
@@ -569,14 +535,31 @@ export const ROUTES: RouteDefinition[] = [
       {
         name: "includeDirSizes",
         description:
-          "Compute recursive byte size for each directory entry (true/false). Budget-bounded — large subtrees may return size: null.",
+          "Compute recursive byte size for each directory entry (true/false). Budget-bounded: large subtrees may return size: null. Not applied to a recursive listing, which carries every file for the client to sum.",
+      },
+      {
+        name: "recursive",
+        description:
+          "List the whole subtree in one response (true/false). Depth-first, each directory's entries in listing order, so grouping by parent path recovers per-directory listings. Bounded: sets truncated when the entry cap or deadline stops the walk, and does not enter directories the workspace gitignore rules exclude, which are named in skipped.",
       },
     ],
     responseBody: z.object({
       path: z.string(),
       entries: z
-        .array(workspaceTreeEntrySchema)
+        .array(workspaceEntrySchema)
         .describe("Directory entry objects"),
+      truncated: z
+        .boolean()
+        .optional()
+        .describe(
+          "A recursive walk stopped at its entry cap or deadline, so deeper entries are missing. Absent from assistants that predate recursive listings.",
+        ),
+      skipped: z
+        .array(z.string())
+        .optional()
+        .describe(
+          "Directories a recursive walk listed but did not enter, whether because a workspace gitignore rule excludes them, they are symlinks, or they could not be read. Each can still be listed on its own. Absent from assistants that predate recursive listings.",
+        ),
     }),
     handler: handleWorkspaceTree,
   },

package/src/runtime/routes/workspace-tree-walk.test.ts

@@ -0,0 +1,244 @@
+/**
+ * The recursive workspace walk: what it enters, what it lists without
+ * entering, the order it reports, and the bounds that stop it.
+ */
+import {
+  chmodSync,
+  mkdirSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { beforeAll, describe, expect, test } from "bun:test";
+
+import { walkWorkspaceTree } from "./workspace-tree-walk.js";
+
+const workspaceDir = process.env.VELLUM_WORKSPACE_DIR!;
+const root = join(workspaceDir, "walk-fixture");
+
+function write(relative: string, content = "x") {
+  const abs = join(root, relative);
+  mkdirSync(join(abs, ".."), { recursive: true });
+  writeFileSync(abs, content);
+}
+
+beforeAll(() => {
+  mkdirSync(root, { recursive: true });
+  write("b-dir/deep/leaf.md");
+  write("b-dir/file-in-b.md");
+  write("a-dir/file-in-a.md");
+  write("top.md");
+  write(".secret/inside-hidden.md");
+  write("node_modules/dep/index.js");
+  // Rules with an inner slash (data/db/) anchor to the workspace root, so
+  // these live there rather than under the fixture directory.
+  mkdirSync(join(workspaceDir, "data", "db"), { recursive: true });
+  writeFileSync(join(workspaceDir, "data", "db", "state.sqlite"), "x");
+  mkdirSync(join(workspaceDir, "data", "avatar"), { recursive: true });
+  writeFileSync(join(workspaceDir, "data", "avatar", "face.png"), "x");
+  mkdirSync(join(workspaceDir, "walk-link-target"), { recursive: true });
+  writeFileSync(join(workspaceDir, "walk-link-target", "behind.md"), "x");
+  try {
+    symlinkSync(
+      join(workspaceDir, "walk-link-target"),
+      join(root, "linked"),
+      "dir",
+    );
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== "EEXIST") {
+      throw err;
+    }
+  }
+});
+
+function walk(
+  overrides: Partial<Parameters<typeof walkWorkspaceTree>[0]> = {},
+) {
+  return walkWorkspaceTree({
+    rootPath: root,
+    workspaceDir,
+    showHidden: false,
+    recursive: true,
+    ...overrides,
+  });
+}
+
+describe("walkWorkspaceTree recursive", () => {
+  test("a non-recursive walk lists one level and reports nothing skipped", async () => {
+    const result = await walk({ recursive: false });
+    expect(result.entries.map((e) => e.path)).not.toContain(
+      "walk-fixture/a-dir/file-in-a.md",
+    );
+    expect(result.entries.map((e) => e.name)).toContain("a-dir");
+    expect(result).toMatchObject({ truncated: false, skipped: [] });
+  });
+
+  test("lists every level, depth-first, each directory in listing order", async () => {
+    const { entries } = await walk();
+    const paths = entries.map((e) => e.path.replace(/^walk-fixture\//, ""));
+    const indexOf = (p: string) => paths.indexOf(p);
+    expect(indexOf("a-dir/file-in-a.md")).toBeGreaterThan(-1);
+    expect(indexOf("b-dir/deep/leaf.md")).toBeGreaterThan(-1);
+    // Root listing first (directories before files), then a-dir's contents
+    // before b-dir's, and b-dir's subdirectory before its file.
+    expect(indexOf("a-dir")).toBeLessThan(indexOf("top.md"));
+    expect(indexOf("top.md")).toBeLessThan(indexOf("a-dir/file-in-a.md"));
+    expect(indexOf("a-dir/file-in-a.md")).toBeLessThan(indexOf("b-dir/deep"));
+    expect(indexOf("b-dir/deep")).toBeLessThan(indexOf("b-dir/file-in-b.md"));
+    expect(indexOf("b-dir/file-in-b.md")).toBeLessThan(
+      indexOf("b-dir/deep/leaf.md"),
+    );
+  });
+
+  test("grouping by parent recovers each directory's own listing", async () => {
+    const { entries } = await walk();
+    const shallow = await walkWorkspaceTree({
+      rootPath: join(root, "b-dir"),
+      workspaceDir,
+      showHidden: false,
+      recursive: false,
+    });
+    const underB = entries.filter(
+      (e) =>
+        e.path.startsWith("walk-fixture/b-dir/") &&
+        !e.path.slice("walk-fixture/b-dir/".length).includes("/"),
+    );
+    expect(underB.map((e) => e.path)).toEqual(
+      shallow.entries.map((e) => e.path),
+    );
+  });
+
+  test("paths use forward slashes", async () => {
+    const { entries } = await walk();
+    expect(entries.every((e) => !e.path.includes("\\"))).toBe(true);
+    expect(entries.map((e) => e.path)).toContain(
+      "walk-fixture/b-dir/deep/leaf.md",
+    );
+  });
+
+  test("hidden directories are neither listed nor entered unless asked", async () => {
+    const hidden = (await walk()).entries.map((e) => e.path);
+    expect(hidden).not.toContain("walk-fixture/.secret");
+    expect(hidden).not.toContain("walk-fixture/.secret/inside-hidden.md");
+    const shown = (await walk({ showHidden: true })).entries.map((e) => e.path);
+    expect(shown).toContain("walk-fixture/.secret/inside-hidden.md");
+  });
+
+  test("a dependency directory is listed at any depth but not entered", async () => {
+    const { entries, skipped } = await walk();
+    const paths = entries.map((e) => e.path);
+    expect(paths).toContain("walk-fixture/node_modules");
+    expect(paths).not.toContain("walk-fixture/node_modules/dep");
+    expect(skipped).toContain("walk-fixture/node_modules");
+  });
+
+  test("root-anchored runtime state is listed, not entered, and named", async () => {
+    const { entries, skipped } = await walk({ rootPath: workspaceDir });
+    const paths = entries.map((e) => e.path);
+    expect(paths).toContain("data/db");
+    expect(paths).not.toContain("data/db/state.sqlite");
+    // A directory the rules do not exclude is entered, and a file the rules
+    // match (*.png) is still listed: only descent is decided by them.
+    expect(paths).toContain("data/avatar/face.png");
+    expect(skipped).toContain("data/db");
+    expect(skipped).not.toContain("data/avatar");
+  });
+
+  test("a symlinked directory is listed, not entered, and reported skipped", async () => {
+    const { entries, skipped } = await walk();
+    const paths = entries.map((e) => e.path);
+    expect(paths).toContain("walk-fixture/linked");
+    expect(paths).not.toContain("walk-fixture/linked/behind.md");
+    expect(skipped).toContain("walk-fixture/linked");
+  });
+
+  test("an unreadable directory is listed, not entered, and reported skipped", async () => {
+    // Root bypasses permission bits, so the check proves nothing there.
+    if (process.getuid?.() === 0) {
+      return;
+    }
+    const locked = join(root, "locked");
+    mkdirSync(locked, { recursive: true });
+    writeFileSync(join(locked, "inside.md"), "x");
+    chmodSync(locked, 0o000);
+    try {
+      const { entries, skipped, truncated } = await walk();
+      const paths = entries.map((e) => e.path);
+      expect(paths).toContain("walk-fixture/locked");
+      expect(paths).not.toContain("walk-fixture/locked/inside.md");
+      expect(skipped).toContain("walk-fixture/locked");
+      expect(truncated).toBe(false);
+    } finally {
+      chmodSync(locked, 0o755);
+      rmSync(locked, { recursive: true, force: true });
+    }
+  });
+
+  test("a directory wider than the remaining room is not scanned", async () => {
+    // Root (5) leaves one slot at a cap of 6; a-dir (1) fits and b-dir (2)
+    // does not. Nothing under b-dir is stat'd: its walk-time stat would
+    // otherwise show up as a listed entry.
+    const wide = join(root, "wide");
+    mkdirSync(wide, { recursive: true });
+    for (let i = 0; i < 50; i++) {
+      writeFileSync(join(wide, `w${i}.md`), "x");
+    }
+    try {
+      const result = await walk({ maxEntries: 7 });
+      const paths = result.entries.map((e) => e.path);
+      expect(paths).toContain("walk-fixture/wide");
+      expect(paths.some((p) => p.startsWith("walk-fixture/wide/"))).toBe(false);
+      expect(result.truncated).toBe(true);
+    } finally {
+      rmSync(wide, { recursive: true, force: true });
+    }
+  });
+
+  test("the deadline is honored inside a directory, not only between them", async () => {
+    // A clock that advances one second per read: the deadline is set at 0,
+    // the check before the first nested directory reads 1000 and passes,
+    // and the first entry inside it reads 2000 and stops the listing. Were
+    // the deadline checked only between directories, that one-entry
+    // directory would be carried and the walk would stop one step later.
+    let reads = 0;
+    const result = await walk({ maxWalkMs: 1500, now: () => reads++ * 1000 });
+    expect(result.truncated).toBe(true);
+    expect(result.entries.length).toBe(5);
+  });
+
+  test("the entry cap stops descent and reports truncated", async () => {
+    // The fixture root lists five entries and holds nine in all.
+    const result = await walk({ maxEntries: 6 });
+    expect(result.entries.length).toBeLessThanOrEqual(6);
+    expect(result.entries.length).toBeGreaterThanOrEqual(5);
+    expect(result.truncated).toBe(true);
+  });
+
+  test("a directory is carried whole or not at all", async () => {
+    // Root (5) plus a-dir (1) fit in 6; b-dir's two entries do not, so
+    // neither of them appears rather than one of them.
+    const { entries } = await walk({ maxEntries: 6 });
+    const paths = entries.map((e) => e.path);
+    expect(paths).toContain("walk-fixture/a-dir/file-in-a.md");
+    expect(paths).not.toContain("walk-fixture/b-dir/deep");
+    expect(paths).not.toContain("walk-fixture/b-dir/file-in-b.md");
+  });
+
+  test("the root listing is whole even under a cap smaller than it", async () => {
+    const result = await walk({ maxEntries: 1 });
+    expect(result.entries.map((e) => e.name)).toContain("top.md");
+    expect(result.truncated).toBe(true);
+  });
+
+  test("the deadline stops the walk and reports truncated", async () => {
+    const result = await walk({ maxWalkMs: -1 });
+    expect(result.truncated).toBe(true);
+  });
+
+  test("directory sizes are null in a recursive walk even when a sizer is given", async () => {
+    const { entries } = await walk({ directorySize: () => 42 });
+    const dir = entries.find((e) => e.type === "directory");
+    expect(dir?.size).toBeNull();
+  });
+});