@caplab/read 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,189 @@
+# @caplab/read
+
+A read-only workspace access package for LLM agents and developer tooling with deterministic path handling, budget-aware file operations, and encoding-safe text processing.
+
+## Why This Package Exists
+
+AI agents and developer tools need safe, predictable file system access. Traditional file APIs can leak outside workspace boundaries, produce unbounded output, or fail silently on encoding issues. `@caplab/read` provides a controlled, read-only interface with explicit budgets and deterministic behavior.
+
+## Problems It Solves
+
+- **Workspace boundary enforcement**: Prevents reading files outside the designated workspace root
+- **Output budgeting**: Limits bytes, lines, and file counts to prevent unbounded responses
+- **Encoding safety**: Auto-detects and handles UTF-8, UTF-8 BOM, UTF-16LE, UTF-16BE without silent failures
+- **Binary detection**: Identifies binary files and handles them predictably
+- **Deterministic ordering**: Same inputs produce the same outputs across runs
+- **Symlink safety**: Resolves symlinks to prevent boundary escape attacks
+
+## What It Intentionally Does Not Do
+
+- Write or modify any files (strictly read-only)
+- Execute code or commands
+- Provide write operations or file system mutations
+- Support arbitrary path traversal outside workspace root
+- Handle encodings outside UTF-8/UTF-16 family
+
+## Installation
+
+```bash
+npm install @caplab/read
+```
+
+## ESM-Only Usage
+
+This package is ESM-only. Use `import` syntax:
+
+```javascript
+import { createWorkspaceReader } from "@caplab/read";
+```
+
+## Quick Start
+
+```javascript
+import { createWorkspaceReader } from "@caplab/read";
+
+const reader = await createWorkspaceReader({
+	workspaceRoot: "./my-project",
+});
+
+// List directory
+const dirResult = await reader.listDirectory("src");
+console.log(dirResult);
+
+// Read file
+const fileResult = await reader.readFile("src/index.ts");
+console.log(fileResult);
+
+// Search files
+for await (const match of reader.fileSearch("function")) {
+	console.log(match);
+}
+```
+
+## API Overview
+
+### `createWorkspaceReader(options)`
+
+Creates a configured workspace reader instance. Throws an error if `workspaceRoot` is invalid (does not exist or is not a directory).
+
+```typescript
+interface WorkspaceReaderOptions {
+	workspaceRoot: string; // Required absolute path
+	maxBytes?: number; // Default: 262144 (256 KiB)
+	maxLines?: number; // Default: 2000
+	maxFiles?: number; // Default: 20
+	maxTotalBytes?: number; // Default: 1048576 (1 MiB)
+	maxEntries?: number; // Default: 1000
+	maxSearchResults?: number; // Default: 200
+	maxDepth?: number; // Default: 10
+}
+```
+
+### `listDirectory(path, options)`
+
+Lists files and directories with deterministic ordering. Returns absolute `path` and normalized `relativePath` for each entry.
+
+```typescript
+interface ListDirectoryOptions {
+	maxDepth?: number; // Default: unlimited
+	includeHidden?: boolean; // Default: false
+	include?: string[]; // Glob patterns
+	exclude?: string[]; // Glob patterns
+	maxEntries?: number; // Default: 1000
+}
+```
+
+### `readFile(path, options)`
+
+Reads a single file with byte and line budgets. Returns absolute `path` and normalized `relativePath`. Supported encodings: UTF-8, UTF-8 BOM, UTF-16LE, UTF-16BE.
+
+```typescript
+interface ReadFileOptions {
+	maxBytes?: number; // Default: 262144
+	maxLines?: number; // Default: 2000
+	encoding?: "utf-8" | "utf-16le" | "utf-16be" | "auto"; // Default: 'auto'
+}
+```
+
+### `readMultipleFiles(paths, options)`
+
+Reads multiple files with bounded parallelism and deterministic admission. Returns results with absolute `path` and normalized `relativePath` for each file.
+
+```typescript
+interface ReadMultipleFilesOptions {
+	maxFiles?: number; // Default: 20
+	maxBytes?: number; // Default: 262144 (per-file)
+	maxTotalBytes?: number; // Default: 1048576
+	maxConcurrency?: number; // Default: 5
+}
+```
+
+### `fileSearch(query, options)`
+
+Search files using an adapter over `@caplab/grep-search`. This is not a second search engine—it delegates search behavior to `@caplab/grep-search` with workspace boundary enforcement and budget limits.
+
+```typescript
+interface FileSearchOptions {
+	regex?: boolean;
+	wholeWord?: boolean;
+	caseSensitive?: boolean;
+	multiline?: boolean;
+	extensions?: string[];
+	ignore?: string[];
+	maxDepth?: number;
+	beforeContext?: number;
+	afterContext?: number;
+	maxResults?: number; // Default: 200
+}
+```
+
+## Default Budgets and Limits
+
+- `readFile.maxBytes`: 262144 (256 KiB)
+- `readFile.maxLines`: 2000
+- `readMultipleFiles.maxFiles`: 20
+- `readMultipleFiles.maxTotalBytes`: 1048576 (1 MiB)
+- `listDirectory.maxEntries`: 1000
+- `fileSearch.maxResults`: 200
+
+## Error Model
+
+Expected operational failures return structured result objects with explicit error codes:
+
+- `file_not_found`: File does not exist
+- `permission_denied`: Insufficient permissions
+- `binary_file`: File detected as binary
+- `unsupported_encoding`: Encoding not supported
+- `path_outside_workspace`: Path outside workspace root
+- `skipped_due_to_budget`: Skipped due to maxTotalBytes exhaustion
+- `skipped_due_to_max_files`: Skipped due to maxFiles limit
+
+Only invalid API usage or invalid configuration throws exceptions.
+
+## Hard Guarantees / Invariants
+
+1. **Read-only guarantee**: The package never mutates workspace state
+2. **Deterministic ordering**: Same input produces same output across runs
+3. **Fail-closed boundaries**: Symlink resolution prevents workspace escape
+4. **Encoding safety**: Text decoding is explicit and predictable
+5. **Output budgeting**: Large files and directory trees don't create unbounded output
+6. **Binary safety**: Binary files are detected and handled predictably
+7. **Path consistency**: All operations return absolute `path` and normalized `relativePath`
+
+## Relationship to @caplab/grep-search
+
+`fileSearch` is an adapter over `@caplab/grep-search`. It:
+
+- Delegates search behavior to `@caplab/grep-search`
+- Enforces workspace boundary with `cwd` parameter
+- Applies default `maxResults` budget
+- Forwards search options (regex, caseSensitive, etc.) via allowlist
+- Does not implement a separate search engine
+
+## Node Version Requirement
+
+Node.js >= 20.0.0
+
+## License
+
+MIT License - see LICENSE file for details

package/dist/cjs/errors/structured.d.ts

@@ -0,0 +1,12 @@
+import type { FileReadResult, DirectoryResult } from '../types/public.js';
+export declare function createFileNotFoundResult(filePath: string, workspaceRoot: string): FileReadResult;
+export declare function createPermissionDeniedResult(filePath: string, workspaceRoot: string): FileReadResult;
+export declare function createBinaryFileResult(filePath: string, workspaceRoot: string): FileReadResult;
+export declare function createUnsupportedEncodingResult(filePath: string, workspaceRoot: string): FileReadResult;
+export declare function createPathOutsideWorkspaceResult(filePath: string, workspaceRoot: string): FileReadResult;
+export declare function createSkippedDueToBudgetResult(filePath: string, workspaceRoot: string): FileReadResult;
+export declare function createSkippedDueToMaxFilesResult(filePath: string, workspaceRoot: string): FileReadResult;
+export declare function createDirectoryNotFoundResult(dirPath: string): DirectoryResult;
+export declare function createDirectoryPermissionDeniedResult(dirPath: string): DirectoryResult;
+export declare function createDirectoryOutsideWorkspaceResult(dirPath: string): DirectoryResult;
+//# sourceMappingURL=structured.d.ts.map

package/dist/cjs/errors/structured.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structured.d.ts","sourceRoot":"","sources":["../../../src/errors/structured.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAG1E,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,cAAc,CAOhG;AAED,wBAAgB,4BAA4B,CAAC,QAAQ,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,cAAc,CAOpG;AAED,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,cAAc,CAO9F;AAED,wBAAgB,+BAA+B,CAAC,QAAQ,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,cAAc,CAOvG;AAED,wBAAgB,gCAAgC,CAAC,QAAQ,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,cAAc,CAOxG;AAED,wBAAgB,8BAA8B,CAAC,QAAQ,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,cAAc,CAOtG;AAED,wBAAgB,gCAAgC,CAAC,QAAQ,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,cAAc,CAOxG;AAED,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,CAM9E;AAED,wBAAgB,qCAAqC,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,CAMtF;AAED,wBAAgB,qCAAqC,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,CAMtF"}

package/dist/cjs/errors/structured.js

@@ -0,0 +1,124 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createFileNotFoundResult = createFileNotFoundResult;
+exports.createPermissionDeniedResult = createPermissionDeniedResult;
+exports.createBinaryFileResult = createBinaryFileResult;
+exports.createUnsupportedEncodingResult = createUnsupportedEncodingResult;
+exports.createPathOutsideWorkspaceResult = createPathOutsideWorkspaceResult;
+exports.createSkippedDueToBudgetResult = createSkippedDueToBudgetResult;
+exports.createSkippedDueToMaxFilesResult = createSkippedDueToMaxFilesResult;
+exports.createDirectoryNotFoundResult = createDirectoryNotFoundResult;
+exports.createDirectoryPermissionDeniedResult = createDirectoryPermissionDeniedResult;
+exports.createDirectoryOutsideWorkspaceResult = createDirectoryOutsideWorkspaceResult;
+const path = __importStar(require("node:path"));
+function createFileNotFoundResult(filePath, workspaceRoot) {
+    return {
+        success: false,
+        error: 'file_not_found',
+        path: filePath,
+        relativePath: path.relative(workspaceRoot, filePath),
+    };
+}
+function createPermissionDeniedResult(filePath, workspaceRoot) {
+    return {
+        success: false,
+        error: 'permission_denied',
+        path: filePath,
+        relativePath: path.relative(workspaceRoot, filePath),
+    };
+}
+function createBinaryFileResult(filePath, workspaceRoot) {
+    return {
+        success: false,
+        error: 'binary_file',
+        path: filePath,
+        relativePath: path.relative(workspaceRoot, filePath),
+    };
+}
+function createUnsupportedEncodingResult(filePath, workspaceRoot) {
+    return {
+        success: false,
+        error: 'unsupported_encoding',
+        path: filePath,
+        relativePath: path.relative(workspaceRoot, filePath),
+    };
+}
+function createPathOutsideWorkspaceResult(filePath, workspaceRoot) {
+    return {
+        success: false,
+        error: 'path_outside_workspace',
+        path: filePath,
+        relativePath: path.relative(workspaceRoot, filePath),
+    };
+}
+function createSkippedDueToBudgetResult(filePath, workspaceRoot) {
+    return {
+        success: false,
+        error: 'skipped_due_to_budget',
+        path: filePath,
+        relativePath: path.relative(workspaceRoot, filePath),
+    };
+}
+function createSkippedDueToMaxFilesResult(filePath, workspaceRoot) {
+    return {
+        success: false,
+        error: 'skipped_due_to_max_files',
+        path: filePath,
+        relativePath: path.relative(workspaceRoot, filePath),
+    };
+}
+function createDirectoryNotFoundResult(dirPath) {
+    return {
+        success: false,
+        error: 'path_not_found',
+        path: dirPath,
+    };
+}
+function createDirectoryPermissionDeniedResult(dirPath) {
+    return {
+        success: false,
+        error: 'permission_denied',
+        path: dirPath,
+    };
+}
+function createDirectoryOutsideWorkspaceResult(dirPath) {
+    return {
+        success: false,
+        error: 'path_outside_workspace',
+        path: dirPath,
+    };
+}
+//# sourceMappingURL=structured.js.map

package/dist/cjs/errors/structured.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"structured.js","sourceRoot":"","sources":["../../../src/errors/structured.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAGA,4DAOC;AAED,oEAOC;AAED,wDAOC;AAED,0EAOC;AAED,4EAOC;AAED,wEAOC;AAED,4EAOC;AAED,sEAMC;AAED,sFAMC;AAED,sFAMC;AAvFD,gDAAkC;AAElC,SAAgB,wBAAwB,CAAC,QAAgB,EAAE,aAAqB;IAC9E,OAAO;QACL,OAAO,EAAE,KAAK;QACd,KAAK,EAAE,gBAAgB;QACvB,IAAI,EAAE,QAAQ;QACd,YAAY,EAAE,IAAI,CAAC,QAAQ,CAAC,aAAa,EAAE,QAAQ,CAAC;KACrD,CAAC;AACJ,CAAC;AAED,SAAgB,4BAA4B,CAAC,QAAgB,EAAE,aAAqB;IAClF,OAAO;QACL,OAAO,EAAE,KAAK;QACd,KAAK,EAAE,mBAAmB;QAC1B,IAAI,EAAE,QAAQ;QACd,YAAY,EAAE,IAAI,CAAC,QAAQ,CAAC,aAAa,EAAE,QAAQ,CAAC;KACrD,CAAC;AACJ,CAAC;AAED,SAAgB,sBAAsB,CAAC,QAAgB,EAAE,aAAqB;IAC5E,OAAO;QACL,OAAO,EAAE,KAAK;QACd,KAAK,EAAE,aAAa;QACpB,IAAI,EAAE,QAAQ;QACd,YAAY,EAAE,IAAI,CAAC,QAAQ,CAAC,aAAa,EAAE,QAAQ,CAAC;KACrD,CAAC;AACJ,CAAC;AAED,SAAgB,+BAA+B,CAAC,QAAgB,EAAE,aAAqB;IACrF,OAAO;QACL,OAAO,EAAE,KAAK;QACd,KAAK,EAAE,sBAAsB;QAC7B,IAAI,EAAE,QAAQ;QACd,YAAY,EAAE,IAAI,CAAC,QAAQ,CAAC,aAAa,EAAE,QAAQ,CAAC;KACrD,CAAC;AACJ,CAAC;AAED,SAAgB,gCAAgC,CAAC,QAAgB,EAAE,aAAqB;IACtF,OAAO;QACL,OAAO,EAAE,KAAK;QACd,KAAK,EAAE,wBAAwB;QAC/B,IAAI,EAAE,QAAQ;QACd,YAAY,EAAE,IAAI,CAAC,QAAQ,CAAC,aAAa,EAAE,QAAQ,CAAC;KACrD,CAAC;AACJ,CAAC;AAED,SAAgB,8BAA8B,CAAC,QAAgB,EAAE,aAAqB;IACpF,OAAO;QACL,OAAO,EAAE,KAAK;QACd,KAAK,EAAE,uBAAuB;QAC9B,IAAI,EAAE,QAAQ;QACd,YAAY,EAAE,IAAI,CAAC,QAAQ,CAAC,aAAa,EAAE,QAAQ,CAAC;KACrD,CAAC;AACJ,CAAC;AAED,SAAgB,gCAAgC,CAAC,QAAgB,EAAE,aAAqB;IACtF,OAAO;QACL,OAAO,EAAE,KAAK;QACd,KAAK,EAAE,0BAA0B;QACjC,IAAI,EAAE,QAAQ;QACd,YAAY,EAAE,IAAI,CAAC,QAAQ,CAAC,aAAa,EAAE,QAAQ,CAAC;KACrD,CAAC;AACJ,CAAC;AAED,SAAgB,6BAA6B,CAAC,OAAe;IAC3D,OAAO;QACL,OAAO,EAAE,KAAK;QACd,KAAK,EAAE,gBAAgB;QACvB,IAAI,EAAE,OAAO;KACd,CAAC;AACJ,CAAC;AAED,SAAgB,qCAAqC,CAAC,OAAe;IACnE,OAAO;QACL,OAAO,EAAE,KAAK;QACd,KAAK,EAAE,mBAAmB;QAC1B,IAAI,EAAE,OAAO;KACd,CAAC;AACJ,CAAC;AAED,SAAgB,qCAAqC,CAAC,OAAe;IACnE,OAAO;QACL,OAAO,EAAE,KAAK;QACd,KAAK,EAAE,wBAAwB;QAC/B,IAAI,EAAE,OAAO;KACd,CAAC;AACJ,CAAC"}

package/dist/cjs/factory.d.ts

@@ -0,0 +1,3 @@
+import type { WorkspaceReader, WorkspaceReaderOptions } from './types/public.js';
+export declare function createWorkspaceReader(options: WorkspaceReaderOptions): Promise<WorkspaceReader>;
+//# sourceMappingURL=factory.d.ts.map

package/dist/cjs/factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../src/factory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,sBAAsB,EAAsF,MAAM,mBAAmB,CAAC;AASrK,wBAAsB,qBAAqB,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,eAAe,CAAC,CA2FrG"}

package/dist/cjs/factory.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createWorkspaceReader = createWorkspaceReader;
+const resolver_js_1 = require("./path/resolver.js");
+const guard_js_1 = require("./path/guard.js");
+const directory_js_1 = require("./fs/directory.js");
+const reader_js_1 = require("./fs/reader.js");
+const multi_file_js_1 = require("./read/multi-file.js");
+const adapter_js_1 = require("./search/adapter.js");
+async function createWorkspaceReader(options) {
+    const config = await (0, resolver_js_1.validateWorkspaceRoot)(options.workspaceRoot);
+    if (!config) {
+        throw new Error('Invalid workspace root: path does not exist or is not a directory');
+    }
+    // Apply overrides from options
+    const workspaceConfig = {
+        ...config,
+        maxBytes: options.maxBytes ?? config.maxBytes,
+        maxLines: options.maxLines ?? config.maxLines,
+        maxFiles: options.maxFiles ?? config.maxFiles,
+        maxTotalBytes: options.maxTotalBytes ?? config.maxTotalBytes,
+        maxEntries: options.maxEntries ?? config.maxEntries,
+        maxSearchResults: options.maxSearchResults ?? config.maxSearchResults,
+    };
+    return {
+        async listDirectory(path, options) {
+            const absolutePath = (0, resolver_js_1.resolvePath)(path, workspaceConfig.workspaceRoot);
+            const boundaryCheck = await (0, guard_js_1.validatePathBoundary)(absolutePath, workspaceConfig.workspaceRoot);
+            if (!boundaryCheck.valid) {
+                if (boundaryCheck.error === 'not_found') {
+                    return {
+                        success: false,
+                        error: 'path_not_found',
+                        path: absolutePath,
+                    };
+                }
+                if (boundaryCheck.error === 'permission_denied') {
+                    return {
+                        success: false,
+                        error: 'permission_denied',
+                        path: absolutePath,
+                    };
+                }
+                return {
+                    success: false,
+                    error: 'path_outside_workspace',
+                    path: absolutePath,
+                };
+            }
+            return (0, directory_js_1.listDirectory)(absolutePath, workspaceConfig.workspaceRoot, options ?? {});
+        },
+        async readFile(path, options) {
+            const absolutePath = (0, resolver_js_1.resolvePath)(path, workspaceConfig.workspaceRoot);
+            const boundaryCheck = await (0, guard_js_1.validatePathBoundary)(absolutePath, workspaceConfig.workspaceRoot);
+            if (!boundaryCheck.valid) {
+                if (boundaryCheck.error === 'not_found') {
+                    return {
+                        success: false,
+                        error: 'file_not_found',
+                        path: absolutePath,
+                        relativePath: (0, resolver_js_1.getRelativePath)(absolutePath, workspaceConfig.workspaceRoot),
+                    };
+                }
+                if (boundaryCheck.error === 'permission_denied') {
+                    return {
+                        success: false,
+                        error: 'permission_denied',
+                        path: absolutePath,
+                        relativePath: (0, resolver_js_1.getRelativePath)(absolutePath, workspaceConfig.workspaceRoot),
+                    };
+                }
+                return {
+                    success: false,
+                    error: 'path_outside_workspace',
+                    path: absolutePath,
+                    relativePath: (0, resolver_js_1.getRelativePath)(absolutePath, workspaceConfig.workspaceRoot),
+                };
+            }
+            const maxBytes = options?.maxBytes ?? workspaceConfig.maxBytes;
+            const maxLines = options?.maxLines ?? workspaceConfig.maxLines;
+            const encoding = options?.encoding;
+            return (0, reader_js_1.readFileWithBudget)(absolutePath, maxBytes, maxLines, encoding, workspaceConfig.workspaceRoot);
+        },
+        async readMultipleFiles(paths, options) {
+            return (0, multi_file_js_1.readMultipleFiles)(paths, workspaceConfig, options ?? {});
+        },
+        fileSearch(query, options) {
+            return (0, adapter_js_1.fileSearch)(query, workspaceConfig, options ?? {});
+        },
+    };
+}
+//# sourceMappingURL=factory.js.map

package/dist/cjs/factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.js","sourceRoot":"","sources":["../../src/factory.ts"],"names":[],"mappings":"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"}

package/dist/cjs/fs/binary.d.ts

@@ -0,0 +1,4 @@
+import type { EncodingDetectionResult } from '../types/internal.js';
+export declare function detectEncoding(filePath: string): Promise<EncodingDetectionResult>;
+export declare function isBinaryFile(filePath: string, encoding: 'utf-8' | 'utf-16le' | 'utf-16be'): Promise<boolean>;
+//# sourceMappingURL=binary.d.ts.map

package/dist/cjs/fs/binary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"binary.d.ts","sourceRoot":"","sources":["../../../src/fs/binary.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAIpE,wBAAsB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAYvF;AA2CD,wBAAsB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,UAAU,GAAG,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,CAiClH"}

package/dist/cjs/fs/binary.js

@@ -0,0 +1,116 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectEncoding = detectEncoding;
+exports.isBinaryFile = isBinaryFile;
+const fs = __importStar(require("node:fs/promises"));
+const SNIFF_CHUNK_SIZE = 8192;
+async function detectEncoding(filePath) {
+    try {
+        const handle = await fs.open(filePath, 'r');
+        const buffer = Buffer.alloc(SNIFF_CHUNK_SIZE);
+        const { bytesRead } = await handle.read(buffer, 0, SNIFF_CHUNK_SIZE, 0);
+        await handle.close();
+        const data = buffer.subarray(0, bytesRead);
+        return detectEncodingFromBuffer(data);
+    }
+    catch {
+        return { encoding: 'unknown', bom: false };
+    }
+}
+function detectEncodingFromBuffer(buffer) {
+    if (buffer.length < 2) {
+        return { encoding: 'utf-8', bom: false };
+    }
+    // Check for BOM
+    if (buffer[0] === 0xEF && buffer[1] === 0xBB && buffer[2] === 0xBF) {
+        return { encoding: 'utf-8', bom: true };
+    }
+    if (buffer[0] === 0xFF && buffer[1] === 0xFE) {
+        return { encoding: 'utf-16le', bom: true };
+    }
+    if (buffer[0] === 0xFE && buffer[1] === 0xFF) {
+        return { encoding: 'utf-16be', bom: true };
+    }
+    // Detect UTF-16 without BOM by looking for null bytes
+    let nullByteCount = 0;
+    for (let i = 0; i < Math.min(buffer.length, 100); i++) {
+        if (buffer[i] === 0) {
+            nullByteCount++;
+        }
+    }
+    // If we see many null bytes, it's likely UTF-16
+    if (nullByteCount > 10) {
+        // Determine LE vs BE by looking at pattern
+        if (buffer[0] === 0 && buffer[1] !== 0) {
+            return { encoding: 'utf-16be', bom: false };
+        }
+        if (buffer[0] !== 0 && buffer[1] === 0) {
+            return { encoding: 'utf-16le', bom: false };
+        }
+    }
+    // Default to UTF-8
+    return { encoding: 'utf-8', bom: false };
+}
+async function isBinaryFile(filePath, encoding) {
+    try {
+        const handle = await fs.open(filePath, 'r');
+        const buffer = Buffer.alloc(SNIFF_CHUNK_SIZE);
+        const { bytesRead } = await handle.read(buffer, 0, SNIFF_CHUNK_SIZE, 0);
+        await handle.close();
+        const data = buffer.subarray(0, bytesRead);
+        if (encoding === 'utf-8' || encoding === 'utf-16le' || encoding === 'utf-16be') {
+            // For supported encodings, decode and check for null bytes in decoded text space
+            const decoder = new TextDecoder(encoding, { fatal: false });
+            const decoded = decoder.decode(data, { stream: true });
+            // Check for null bytes in decoded text
+            if (decoded.includes('\0')) {
+                return true;
+            }
+            return false;
+        }
+        // For unsupported encodings, use null-byte heuristic on raw bytes
+        for (let i = 0; i < data.length; i++) {
+            if (data[i] === 0) {
+                return true;
+            }
+        }
+        return false;
+    }
+    catch {
+        return true;
+    }
+}
+//# sourceMappingURL=binary.js.map

package/dist/cjs/fs/binary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"binary.js","sourceRoot":"","sources":["../../../src/fs/binary.ts"],"names":[],"mappings":"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"}

package/dist/cjs/fs/directory.d.ts

@@ -0,0 +1,3 @@
+import type { DirectoryResult, ListDirectoryOptions } from '../types/public.js';
+export declare function listDirectory(dirPath: string, workspaceRoot: string, options?: ListDirectoryOptions): Promise<DirectoryResult>;
+//# sourceMappingURL=directory.d.ts.map

package/dist/cjs/fs/directory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"directory.d.ts","sourceRoot":"","sources":["../../../src/fs/directory.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAkB,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAahG,wBAAsB,aAAa,CACjC,OAAO,EAAE,MAAM,EACf,aAAa,EAAE,MAAM,EACrB,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,eAAe,CAAC,CA6H1B"}