feat: add glob tool

src/index.ts

@@ -98,6 +98,7 @@ export {
   fileReadTool,
   fileWriteTool,
   fileEditTool,
+  globTool,
   grepTool,
 } from './tool/built-in/index.js'
 

src/tool/built-in/fs-walk.ts

@@ -0,0 +1,97 @@
+/**
+ * Shared recursive directory walk for built-in file tools.
+ *
+ * Used by {@link grepTool} and {@link globTool} so glob filtering and skip
+ * rules stay consistent.
+ */
+
+import { readdir, stat } from 'fs/promises'
+import { join } from 'path'
+
+/** Directories that are almost never useful to traverse for code search. */
+export const SKIP_DIRS = new Set([
+  '.git',
+  '.svn',
+  '.hg',
+  'node_modules',
+  '.next',
+  'dist',
+  'build',
+])
+
+export interface CollectFilesOptions {
+  /** When set, stop collecting once this many paths are gathered. */
+  readonly maxFiles?: number
+}
+
+/**
+ * Recursively walk `dir` and return file paths, honouring {@link SKIP_DIRS}
+ * and an optional filename glob pattern.
+ */
+export async function collectFiles(
+  dir: string,
+  glob: string | undefined,
+  signal: AbortSignal | undefined,
+  options?: CollectFilesOptions,
+): Promise<string[]> {
+  const results: string[] = []
+  await walk(dir, glob, results, signal, options?.maxFiles)
+  return results
+}
+
+async function walk(
+  dir: string,
+  glob: string | undefined,
+  results: string[],
+  signal: AbortSignal | undefined,
+  maxFiles: number | undefined,
+): Promise<void> {
+  if (signal?.aborted === true) return
+  if (maxFiles !== undefined && results.length >= maxFiles) return
+
+  let entryNames: string[]
+  try {
+    entryNames = await readdir(dir, { encoding: 'utf8' })
+  } catch {
+    return
+  }
+
+  for (const entryName of entryNames) {
+    if (signal !== undefined && signal.aborted) return
+    if (maxFiles !== undefined && results.length >= maxFiles) return
+
+    const fullPath = join(dir, entryName)
+
+    let entryInfo: Awaited<ReturnType<typeof stat>>
+    try {
+      entryInfo = await stat(fullPath)
+    } catch {
+      continue
+    }
+
+    if (entryInfo.isDirectory()) {
+      if (!SKIP_DIRS.has(entryName)) {
+        await walk(fullPath, glob, results, signal, maxFiles)
+      }
+    } else if (entryInfo.isFile()) {
+      if (glob === undefined || matchesGlob(entryName, glob)) {
+        results.push(fullPath)
+      }
+    }
+  }
+}
+/** 
+ * Minimal glob match supporting `*.ext` and `**<pattern>` forms.
+ * 
+*/
+
+
+export function matchesGlob(filename: string, glob: string): boolean {
+  const pattern = glob.startsWith('**/') ? glob.slice(3) : glob
+  const regexSource = pattern
+    .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+    .replace(/\*/g, '.*')
+    .replace(/\?/g, '.')
+  const re = new RegExp(`^${regexSource}$`, 'i')
+  return re.test(filename)
+}

src/tool/built-in/glob.ts

@@ -0,0 +1,99 @@
+/**
+ * Built-in glob tool.
+ *
+ * Lists file paths under a directory matching an optional filename glob.
+ * Does not read file contents — use {@link grepTool} to search inside files.
+ */
+
+import { stat } from 'fs/promises'
+import { basename, relative } from 'path'
+import { z } from 'zod'
+import type { ToolResult } from '../../types.js'
+import { collectFiles, matchesGlob } from './fs-walk.js'
+import { defineTool } from '../framework.js'
+
+const DEFAULT_MAX_FILES = 500
+
+export const globTool = defineTool({
+  name: 'glob',
+  description:
+    'List file paths under a directory that match an optional filename glob. ' +
+    'Does not read file contents — use `grep` to search inside files. ' +
+    'Skips common bulky directories (node_modules, .git, dist, etc.). ' +
+    'Paths in the result are relative to the process working directory. ' +
+    'Results are capped by `maxFiles`.',
+
+  inputSchema: z.object({
+    path: z
+      .string()
+      .optional()
+      .describe(
+        'Directory to list files under. Defaults to the current working directory.',
+      ),
+    pattern: z
+      .string()
+      .optional()
+      .describe(
+        'Filename glob (e.g. "*.ts", "**/*.json"). When omitted, every file ' +
+          'under the directory is listed (subject to maxFiles and skipped dirs).',
+      ),
+    maxFiles: z
+      .number()
+      .int()
+      .positive()
+      .optional()
+      .describe(
+        `Maximum number of file paths to return. Defaults to ${DEFAULT_MAX_FILES}.`,
+      ),
+  }),
+
+  execute: async (input, context): Promise<ToolResult> => {
+    const root = input.path ?? process.cwd()
+    const maxFiles = input.maxFiles ?? DEFAULT_MAX_FILES
+    const signal = context.abortSignal
+
+    let linesOut: string[]
+    let truncated = false
+
+    try {
+      const info = await stat(root)
+      if (info.isFile()) {
+        const name = basename(root)
+        if (
+          input.pattern !== undefined &&
+          !matchesGlob(name, input.pattern)
+        ) {
+          return { data: 'No files matched.', isError: false }
+        }
+        linesOut = [relative(process.cwd(), root) || root]
+      } else {
+        const collected = await collectFiles(root, input.pattern, signal, {
+          maxFiles: maxFiles + 1,
+        })
+        truncated = collected.length > maxFiles
+        const capped = collected.slice(0, maxFiles)
+        linesOut = capped.map((f) => relative(process.cwd(), f) || f)
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : 'Unknown error'
+      return {
+        data: `Cannot access path "${root}": ${message}`,
+        isError: true,
+      }
+    }
+
+    if (linesOut.length === 0) {
+      return { data: 'No files matched.', isError: false }
+    }
+
+    const sorted = [...linesOut].sort((a, b) => a.localeCompare(b))
+    const truncationNote = truncated
+      ? `\n\n(listing capped at ${maxFiles} paths; raise maxFiles for more)`
+      : ''
+
+    return {
+      data: sorted.join('\n') + truncationNote,
+      isError: false,
+    }
+  },
+})

src/tool/built-in/grep.ts

@@ -8,28 +8,18 @@
  */
 
 import { spawn } from 'child_process'
-import { readdir, readFile, stat } from 'fs/promises'
-// Note: readdir is used with { encoding: 'utf8' } to return string[] directly.
-import { join, relative } from 'path'
+import { readFile, stat } from 'fs/promises'
+import { relative } from 'path'
 import { z } from 'zod'
 import type { ToolResult } from '../../types.js'
 import { defineTool } from '../framework.js'
+import { collectFiles } from './fs-walk.js'
 
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
 
 const DEFAULT_MAX_RESULTS = 100
-// Directories that are almost never useful to search inside
-const SKIP_DIRS = new Set([
-  '.git',
-  '.svn',
-  '.hg',
-  'node_modules',
-  '.next',
-  'dist',
-  'build',
-])
 
 // ---------------------------------------------------------------------------
 // Tool definition
@@ -42,6 +32,7 @@ export const grepTool = defineTool({
     'Returns matching lines with their file paths and 1-based line numbers. ' +
     'Use the `glob` parameter to restrict the search to specific file types ' +
     '(e.g. "*.ts"). ' +
+    'To list matching file paths without reading contents, use the `glob` tool. ' +
     'Results are capped by `maxResults` to keep the response manageable.',
 
   inputSchema: z.object({
@@ -270,79 +261,6 @@ async function runNodeSearch(
   }
 }
 
-// ---------------------------------------------------------------------------
-// File collection with glob filtering
-// ---------------------------------------------------------------------------
-
-/**
- * Recursively walk `dir` and return file paths, honouring `SKIP_DIRS` and an
- * optional glob pattern.
- */
-async function collectFiles(
-  dir: string,
-  glob: string | undefined,
-  signal: AbortSignal | undefined,
-): Promise<string[]> {
-  const results: string[] = []
-  await walk(dir, glob, results, signal)
-  return results
-}
-
-async function walk(
-  dir: string,
-  glob: string | undefined,
-  results: string[],
-  signal: AbortSignal | undefined,
-): Promise<void> {
-  if (signal?.aborted === true) return
-
-  let entryNames: string[]
-  try {
-    // Read as plain strings so we don't have to deal with Buffer Dirent variants.
-    entryNames = await readdir(dir, { encoding: 'utf8' })
-  } catch {
-    return
-  }
-
-  for (const entryName of entryNames) {
-    if (signal !== undefined && signal.aborted) return
-
-    const fullPath = join(dir, entryName)
-
-    let entryInfo: Awaited<ReturnType<typeof stat>>
-    try {
-      entryInfo = await stat(fullPath)
-    } catch {
-      continue
-    }
-
-    if (entryInfo.isDirectory()) {
-      if (!SKIP_DIRS.has(entryName)) {
-        await walk(fullPath, glob, results, signal)
-      }
-    } else if (entryInfo.isFile()) {
-      if (glob === undefined || matchesGlob(entryName, glob)) {
-        results.push(fullPath)
-      }
-    }
-  }
-}
-
-/**
- * Minimal glob match supporting `*.ext` and `**\/<pattern>` forms.
- */
-function matchesGlob(filename: string, glob: string): boolean {
-  // Strip leading **/ prefix — we already recurse into all directories
-  const pattern = glob.startsWith('**/') ? glob.slice(3) : glob
-  // Convert shell glob characters to regex equivalents
-  const regexSource = pattern
-    .replace(/[.+^${}()|[\]\\]/g, '\\$&') // escape special regex chars first
-    .replace(/\*/g, '.*')                  // * -> .*
-    .replace(/\?/g, '.')                   // ? -> .
-  const re = new RegExp(`^${regexSource}$`, 'i')
-  return re.test(filename)
-}
-
 // ---------------------------------------------------------------------------
 // ripgrep availability check (cached per process)
 // ---------------------------------------------------------------------------

src/tool/built-in/index.ts

@@ -11,9 +11,10 @@ import { bashTool } from './bash.js'
 import { fileEditTool } from './file-edit.js'
 import { fileReadTool } from './file-read.js'
 import { fileWriteTool } from './file-write.js'
+import { globTool } from './glob.js'
 import { grepTool } from './grep.js'
 
-export { bashTool, fileEditTool, fileReadTool, fileWriteTool, grepTool }
+export { bashTool, fileEditTool, fileReadTool, fileWriteTool, globTool, grepTool }
 
 /**
  * The ordered list of all built-in tools.  Import this when you need to
@@ -29,6 +30,7 @@ export const BUILT_IN_TOOLS: ToolDefinition<any>[] = [
   fileWriteTool,
   fileEditTool,
   grepTool,
+  globTool,
 ]
 
 /**