workspace.fs.grep and workspace.fs.find Features in Cloudflare Computer

Both workspace.fs.grep and workspace.fs.find provide streaming-friendly file system search capabilities, with grep scanning file contents for literal or regex patterns and find locating files by glob-style path patterns, both supporting pagination via limit/offset and filtering via include and ignoreCase options.

The Cloudflare Computer repository exposes a high-level file system API through workspace.fs, enabling developers to programmatically search codebases without loading entire directories into memory. The grep and find methods serve distinct but complementary roles in packages/computer/src/tools/fs/grep.ts and packages/computer/src/tools/fs/find.ts respectively, and are documented extensively in docs/09_tool_interface.md and docs/README.md.

workspace.fs.grep Features

Content Search Capabilities

workspace.fs.grep searches file contents recursively starting from a specified directory. It supports both literal string matching and regular expression patterns when the regex option is enabled. As implemented in packages/computer/src/tools/fs/grep.ts, the method streams files through a line-by-line scanning interface that stops once the requested limit is reached, preventing memory exhaustion on large codebases.

Configuration Options

The method accepts an options object supporting these parameters:

• ignoreCase: Enables case-insensitive matching across file contents.
• regex: Treats the query string as a JavaScript regular expression rather than a literal.
• include: Glob pattern to restrict search to specific file types (e.g., "*.ts").
• limit: Maximum number of matches to return per call for pagination.
• offset: Number of matches to skip, enabling result set pagination.
• context: Number of surrounding lines to include with each match, useful for viewing code context.

Match Results Structure

Each match returned by workspace.fs.grep contains:

• path: Absolute file path where the match occurred.
• line: Line number (1-indexed) of the match.
• column: Column number where the match begins.
• text: The actual matched text content.
• context: Optional array of surrounding lines when the context option is specified.

workspace.fs.find Features

Path-Based Search

workspace.fs.find locates files and directories whose paths match a glob-style pattern, starting from a root directory. Unlike grep, this method does not inspect file contents; it only evaluates path strings against the provided pattern. According to the implementation in packages/computer/src/tools/fs/find.ts at line 44, the search leverages the underlying @cloudflare/dofs storage layer for efficient tree walking with early termination when limits are reached.

Filtering and Pagination

The method supports controlled enumeration through these options:

• ignoreCase: Performs case-insensitive glob matching against file paths.
• include: Additional glob filter to further restrict results by file extension or naming convention.
• limit: Caps the maximum number of entries returned in a single call.
• offset: Skips the first n entries to support pagination through large result sets.

File Metadata Results

Each result from workspace.fs.find returns a ThinkFileInfo object containing rich metadata:

• path: Absolute path to the file or directory.
• name: The filename or directory name.
• type: Either "file" or "directory".
• mimeType: Detected MIME type for files.
• size: File size in bytes.
• createdAt and updatedAt: Unix timestamps for creation and modification.

Implementation and Performance Details

Both methods utilize the @cloudflare/dofs storage layer for streaming results without loading complete file trees into memory. The grep implementation specifically avoids reading entire files unless necessary for matching, while find stops enumeration immediately upon reaching the specified limit. As noted in docs/09_tool_interface.md lines 195-197, these methods respect the pagination contracts to prevent blocking the event loop on large repositories.

Code Examples

Grep for TODO Comments

The following example, referenced from docs/README.md line 166, demonstrates case-insensitive content search:

const hits = await workspace.fs.grep("TODO", "/workspace", {
  ignoreCase: true,
  limit: 20
});

// Result structure:
// {
//   path: '/workspace/src/app.ts',
//   line: 42,
//   column: 5,
//   text: ' // TODO: refactor this function'
// }

Find Markdown Files

Locate all Markdown files under a documentation directory:

const markdownFiles = await workspace.fs.find('/docs', '*.md', {
  ignoreCase: true,
  limit: 50
});

// Returns ThinkFileInfo objects:
// {
//   path: '/docs/README.md',
//   name: 'README.md',
//   type: 'file',
//   mimeType: 'text/markdown',
//   size: 1234,
//   createdAt: 1698392400000,
//   updatedAt: 1698392400000
// }

Regex Search with Context

Search for error patterns with surrounding context lines:

const errors = await workspace.fs.grep('\\bERROR\\b', '/logs', {
  regex: true,
  context: 2,
  include: "*.log",
  limit: 100
});

Summary

• workspace.fs.grep scans file contents for literal text or regular expressions, supporting options for case insensitivity, file filtering, pagination (limit/offset), and result context.
• workspace.fs.find searches for files and directories by glob path patterns, returning ThinkFileInfo metadata including MIME types, sizes, and timestamps.
• Source Locations: packages/computer/src/tools/fs/grep.ts and packages/computer/src/tools/fs/find.ts contain the core implementations.
• Performance: Both use streaming pagination via @cloudflare/dofs to handle large repositories efficiently.
• Documentation: Detailed specifications appear in docs/09_tool_interface.md and usage examples in docs/README.md.

Frequently Asked Questions

What is the difference between workspace.fs.grep and workspace.fs.find?

workspace.fs.grep inspects the actual contents of files to locate text or regex matches, returning specific line numbers and column positions, while workspace.fs.find only evaluates file paths against glob patterns to locate items by name or extension, returning file metadata without examining content.

How does pagination work with these search methods?

Both methods accept limit and offset options in their configuration objects. Set limit to define the maximum results per request and offset to skip previously retrieved items, enabling efficient pagination through large datasets without loading entire result sets into memory at once.

Can workspace.fs.grep use regular expressions?

Yes. Pass regex: true in the options parameter to interpret the query as a JavaScript regular expression. The implementation compiles the pattern and performs efficient line-by-line matching across the file tree, as detailed in packages/computer/src/tools/fs/grep.ts.

What metadata does workspace.fs.find return?

Each result returns a ThinkFileInfo object containing the absolute path, filename, type classification (file or directory), MIME type, size in bytes, and Unix timestamps for creation and modification times, consistent with the metadata returned by workspace.fs.stat.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}